Programming for a Handheld PC

A Handheld PC (H/PC)is a mobile computer that runs Microsoft® Windows® CE software. An H/PC supports a variety of hardware options and is designed to be a companion to a desktop computer. The following table shows the software that runs on an H/PC.

Handheld PC software
Includes
Microsoft® Windows® CE for the Handheld PC | Microsoft® Windows® CE version 2.0 and additional software
Microsoft® Windows® CE, Handheld PC Edition, version 3.0 | Microsoft® Windows® CE version 2.10 and additional software
Microsoft® Windows® CE, Handheld PC Professional Edition, version 3.0 | Microsoft® Windows® CE version 2.10 and additional software

You can write applications for an H/PC using the Microsoft® Visual C++® development system or the Microsoft® Visual Basic® development system. For more information about using these Microsoft products to develop Windows CE applications, see (some web site.)

  • Hardware
  • Managing memory
  • Developer’s Tools
  • Communications
  • Controls
  • Bundled Applications

This section highlights the unique aspects of Windows CE for the Handheld PC. Unless specified, any reference to Windows CE refers to Windows CE for the Handheld PC. For comprehensive information on developing a Windows CE application, see the online Help included with any Windows CE software development kit (SDK).


Hardware

Original equipment manufacturers (OEMs) have a variety of hardware options when building H/PCs. The following list describes the hardware components for an H/PC.

  • Screen

    Windows CE 2.0 supports an LCD with a resolution of 480 x 240, or higher in landscape orientation. The screen can have a color resolution of 2, 4, or 8 bits per pixel (bpp), and can also use 3–3–2 mode. The pixel arrangement renders the display in black and white, grayscale, or 256 colors.

    Windows CE 2.10 can also support a 640 x 480 or 800 x 600 pixel resolution and a dot pitch of either .24, .26, or .28. It can also support 8, 16, 24, or 32 bpp.

  • Touch panel

    Windows CE 2.0 supports a resistive touch panel covering the screen. The touch panel enables the screen to work like a mouse on a desktop computer. Tapping the touch screen sends the same kind of messages that clicking with the left mouse button does on a desktop computer. The user can also select and drag items. In order to sense quick changes in user input, the touch screen has a refresh rate of at least 100 samples per second. Because most H/PCs have no mouse, cursor support is limited to a spinning hourglass used as a wait cursor. You cannot change the shape of the cursor to indicate an active target, such as a hyperlink.

    Windows CE 2.10 supports pointing devices. Some H/PCs may include a pointing device as an alternative to a touch panel.

  • Pointing device

    Windows CE 2.10 supports pointing technology. Many devices running Windows CE 2.10 contain a touch panel. However, some OEMs may choose to implement a mouse, trackball, or an eraser pointer device, instead. An H/PC with an alternative pointing device supports various types of cursors.

  • Keyboard

    Windows CE 2.0 supports a QWERTY keyboard with some keys omitted. QWERTY is the standard English-language keyboard layout named for the six leftmost characters in the top row of alphabetical characters. An H/PC keyboard includes a CTRL key, an ALT key, and two SHIFT keys. Infrequently used keys, such as PRINT SCREEN and SCROLL LOCK, are not included. The keyboard supports separate key-down and key-up events.

    Windows CE 2.10 supports a a keyboard with half-travel, near-regular size keys. Windows CE 2.10 also includes support for function keys. However, some hardware solutions, such as the tablet-style H/PC, do not necessarily come with a keyboard. An OEM may choose to install a slide-out keyboard or an external keyboard. Alternately, the tablet style may incorporate software input panel technology, such as that found on a Palm-size PC.

  • Audio input

    Windows CE 2.10 supports a microphone. This support requires 16-bit sampling at 8 kHz, while a codec compresses the recording to 2.4 kilobits per second (Kbps). The codec is identical to a desktop computer audio compression manager (ACM). Some OEMs may add a microphone jack to the hardware for an external microphone. The jack is transparent to the software.

  • Audio output

    You can use the built-in speakers to play a variety of sounds, such as notification events, voice recordings, or other .wav files. In addition, you can use the speakers like a pager for notification or for dual-tone multifrequency (DTMF) dialing output. Some OEMs may add a headphone jack for headphones, external speakers, or other audio-out hardware. This jack is transparent to the software.

  • Notification options

    The most common notification option for an H/PC is the external LED. This flashing light provides a simple, low-power reminder for the user. Windows CE 2.0 supports a notification button. This button lets a user acknowledge notifications without having to open the H/PC. The notification button is often incorporated into the notification LED. Another notification option is a silent buzzer.

  • Power

    An H/PC can run at least 10 hours on its main battery source. An H/PC also has a backup battery to avoid data loss when a user changes the main battery. Later versions of H/PC hardware include rechargeable battery packs, rather than AA alkaline batteries, and include an external port for alternating current (AC).

  • Processors

    Windows CE 2.0 supports the following chip sets:

    • MIPS 4102 and 4111
    • PR 3912
    • SH3

    Windows CE 2.10 supports the following chip sets:

    • ARM SA1100
    • MIPS R3912, R4102, and R4111
    • Hitachi SH3 and SH4
    • x86

    Note A MIPS processor has a lower code density than comparable processors. Consequently, a device with a MIPS microprocessor usually has more ROM than comparable devices with another chip set. A device with a MIPS microprocessor alsouses more memory for running applications.

  • Memory
Handheld PC software
RAM
ROM
Microsoft® Windows® CE for the Handheld PC | Expandable to at least 16 MB | Includes 4 MB
Microsoft® Windows® CE, Handheld PC Edition, version 3.0 | Requires at least 8 MB | Requires at least 16 MB
Microsoft® Windows® CE, Handheld PC Professional Edition, version 3.0 | Requires at least 8 MB | Requires at least 16 MB

Additional on the CPU used, the components that the OEM includes with the custom operating system (OS), and the number of components compressed in ROM.

Because it is important to conserve memory, an OEM may compress some components of the software for an H/PC into ROM. When a user needs a component, the operating system decompresses that component and transfers it to RAM. Because of this transfer, compressed files slow performance. This effect is usually more pronounced on MIPS processors.

  • Mass storage

    OEMs may choose to add mass storage devices for storing database files, documents, and other large pieces of information. Due to power constraints, the most common mass storage devices are the Iomega Click! drive, the PC Card, and CompactFlash.

    • Iomega Click! drive

      The Click! drive contains a removable 40-MB disk, about 3 mm thick and 2 inches square.

    • PC Card

      PC Card slots are a common option for an H/PC. A PC Card slot can be used for internal modems, one-way pagers, and other peripherals. In addition to standard PC Card slot capabilities, a PC Card can programmatically request power from a PC Card slot. An H/PC can also receive interrupts from PC Cards, even if the H/PC is in suspended mode. Because Windows CE supports only a portion of the Personal Computer Memory Card International Association (PCMCIA) standard, not all peripherals are supported. However, because Windows CE supports installable device drivers, third-party software and hardware vendors can add support for additional devices by providing device drivers that you can install into RAM on an H/PC.

    • CompactFlash

      A CompactFlash slot can be used for storage cards, Ethernet cards, bar code readers, modems, and other peripherals. Like PC Card slots, CompactFlash slots support sending interrupts and can request power from an H/PC.

  • Serial port

    The built-in, nine-pin serial port on an H/PC operates identically to an RS232-compliant serial port on a desktop computer. Applications use the serial port for communications between an H/PC and other hardware. An H/PC can connect to a desktop computer, using a serial cable or optional docking cradle that is connected to the computer. A cradle is available from many H/PC manufacturers. The serial port can be used as a printer port, as well. Windows CE 2.10 supports a serial port universal asynchronous receiver-transmitter (UART) and a maximum transmission speed of at least 115 kbps

  • Infrared communications serial port

    The infrared (IR) port on an H/PC supports Point-to-Point Protocol (PPP) serial connections with any hardware that is compliant with Infrared Data Association (IrDA) standards, such as a desktop computer or another Windows CE–based platform. The IR port also supports printers that are IR-enabled and those with parallel interfaces.

    You can establish connections between two IrDA-compliant devices that have ports aligned within 15 degrees of each other. They must also be no more than 3 feet apart. IrDA specifications provide for serial IR links operating at speeds up to 115.2 KBps. Windows CE 2.10 supports Fast IR.

  • Universal Serial Bus (USB)

    Windows CE 2.10 supports a USB host, which allows an H/PC to use USB peripherals. An H/PC requires OEM-supplied drivers for any USB peripheral device that the OEM supports.

  • Internal modem

    In order to free the PC Card slot for other uses, many H/PCs contain an internal modem. Windows CE 2.10 supportsmodems that operate at a speed of at least 28.8 kbps and have their own UART.

  • VGA out port

    The VGA-out port connects an H/PC to a VGA monitor. The port supports at least 640 x 480 resolution. This port can transmit data that is not seen on an H/PC user’s display. For example, the Handheld Pro Edition software can display a slide created with the Microsoft® Pocket PowerPoint® presentation graphics program through the VGA-out port, while displaying a document created with the Microsoft® Pocket Word word processor on an H/PC user’s screen.


Managing Memory

Memory management on an H/PC is similar to memory management on a desktop computer. However, due to the compact size of an H/PC, low-memory situations are more common on an H/PC than on a desktop computer. This section discusses how to develop applications that respond to low-memory situations and how an H/PC prompts a user to resolve low-memory situations.


Handling Low-Memory Situations on an H/PC

Windows CE uses a series of memory thresholds to conserve system resources. The following table shows values for memory thresholds. The values are based on a 1-KB memory page; values for a 4-KB memory page are provided in parentheses.

Threshold
Value
Description
Hibernation threshold 128 KB
(160 KB) 		The point at which a system enters a limited-memory state. A system sends a WM_HIBERNATE message when its memory falls below this value.
Low-memory threshold 64 KB
(48 KB) 		The minimum available memory that a system must maintain when it is in a low-memory state.
Critical-memory threshold 16 KB
(48 KB) 		The minimum available memory that a system must maintain when it is in a critical-memory state.

The following table shows maximum memory allocations in limited-memory states.

Limited-memory state
Value
Description
Low-memory | 16 KB | The maximum amount of memory that the system allows the VirtualAlloc function to allocate when the system is in a low-memory state.
Critical memory | 8 KB | The maximum amount of memory that the system allows VirtualAlloc to allocate when the system is in a critical memory state.

Windows CE must respond to four limited-memory scenarios. These scenarios occur when an application does one of the following:

  • Requests less memory than the low-memory maximum
  • Requests more memory than the low-memory maximum
  • Requests less memory than the critical-memory maximum
  • Requests more memory than the critical-memory maximum

If an application calls VirtualAlloc and requests less memory than the low-memory maximum but enough to cause the system to fall below the low-memory threshold, the system displays a System Out of Memory dialog box. This dialog box is discussed in more detail in the next section. In this case, the user must either select applications for the system to close or allocate more RAM to program memory. If the user chooses to close applications, the system sends WM_CLOSE messages. If an application receives a WM_CLOSE message but does not shut down within eight seconds, the system displays an End Task/Wait dialog box. This gives the user the choice of terminating the application or seeing if the application closes itself.

Any VirtualAlloc call fails if it causes the amount of available memory in the system to fall below the low-memory threshold. The system does not display the System Out of Memory dialog box. The LocalAlloc function does not necessarily have the same constraints as VirtualAlloc. Depending on the state of the system heap, a call to LocalAlloc succeeds even if it makes memory fall below the low-memory threshold.

If an application calls VirtualAlloc to request less memory than the critical memory maximum, the system displays the System Out of Memory dialog box. The user must either select applications for the system to close or increase the amount of RAM allocated to program memory, if there is any available RAM. The system calls the TerminateProcess function to terminate any applications selected by the user.

Applications that call VirtualAlloc fail if the function causes the amount of available memory in the system to fall below the critical memory threshold. Depending on the state of the system heap, a call to LocalAlloc can succeed even if it makes memory fall below the low-memory threshold.

Note The system polls memory every five seconds.

It is possible to totally skip over both the low-memory and critical memory thresholds. Whenever the system attempts to allocate more than 16 KB of memory, it has the potential to fail without displaying the System Out of Memory dialog box and without sending a low-memory warning to the user. In the same manner, any memory allocation greater than 8 KB while in a low-memory regime has the potential to fail. Therefore, your application should not allocate large amounts of memory in its shutdown code. The user already knows that a low-memory situation exists. Instead, use small memory allocations, such as 4 KB or less, whenever possible. By consistently using small memory allocations in your applications, you avoid bypassing the low-memory and critical-memory thresholds. Your memory allocations activate the System Out of Memory dialog boxes and give a user the opportunity to respond.


Application Hibernation

Windows CE uses the WM_HIBERNATE message as its primary mechanism for asking applications to free memory. When freeing memory is required, the system posts the message to one or more applications, beginning with the application that has been inactive the longest. It requests memory from the active application last and does not send WM_HIBERNATE messages to invisible windows.

Note Hibernating is vital for applications running on an H/PC. All H/PC applications must have a handler for WM_HIBERNATE.

When the system brings an application to the foreground, it sends an WM_ACTIVATE message. If the hibernating application has previously released memory, the system does not restore its memory resources to the prehibernation state. Applications should have a WM_ACTIVATE handler that can restore memory resources following hibernation.

An application must take the following actions when it receives a WM_HIBERNATE message:

  • Free any large blocks of memory that were allocated by VirtualAlloc, for example, a cache.
  • Free as many Graphics, Windowing, and Events Subsystem (GWES) objects as possible, including windows, bitmaps, and device contexts, because they use large amounts of memory.
  • Save the state of the heap in order to restore it later, and then free the entire heap.

As the amount of available memory drops, the system posts WM_HIBERNATE messages at an increasing rate. If the system reaches a situation where a call to VirtualAlloc is about to fail, it tries to free pages by shrinking stacks. The system shrinks stacks in random order to minimize the risk of a stack fault, which causes an application to fail. The system also frees memory by discarding read-only pageable pages. If the system cannot free any stack pages, VirtualAlloc fails, and the function is returned to the application as a failed function call.


System Out of Memory Dialog Box

Windows CE displays a System Out of Memory dialog box in some low-memory situations. This dialog box informs the user that memory is critically low and prompts the user either to close applications or to increase the amount of RAM allocated to program memory. This dialog box is a special System Modal dialog box that freezes the rest of the system. When it is invoked, socket connections stop functioning and other threads stop running.

After the System Out of Memory dialog box closes, any applications selected by the user are shut down just as if the Close button had been chosen. Applications have eight seconds to close. If more memory is requested after four seconds have passed and memory is still critically low, the dialog box reappears.

Note The success of an approach that sends a WM_CLOSE message when memory is low depends on the ability of an application to shut down in response, while allocating little additional memory in the process. If your application requires a significant amount of memory to shut down, try caching the needed memory. For example, you could hide a Do You Want to Save Your Document dialog box, and then make it visible if you need to close the application unexpectedly.


Power Management

The primary function of power management is to increase the battery life of an H/PC. Power management is accomplished by providing accurate estimates of remaining battery life and notifying a user when batteries are nearly depleted. Power management for an H/PC is based on the following assumptions:

  • The H/PC is used less than two hours per day in bursts from five minutes to one hour.
  • The display is powered 100 percent of the time during use.
  • The device runs less than 10 percent of the time during typical use.
  • The device uses both main batteries and a backup battery.
  • The device has no nonvolatile, writable memory.
  • Maximum battery life is obtained without PC Card or flash storage devices or those that require very little power from the device batteries. Storage devices that draw appreciable power from internal batteries significantly reduce battery life.

Power Management States

An H/PC manages power by allowing the operating system to automatically select one of three operating states, based on user and programming activities. These states are dead, suspend, and on.

Dead State

In the dead state, an H/PC uses no power. It has no batteries, or the batteries have no power. All contents of RAM are lost. The user purchases a device in this state.

Suspend State

In the suspend state, an H/PC uses minimal power to maintain its clock, its applications, and the persistent data stored in RAM. To reduce power requirements, an H/PC removes power from unneeded circuits and devices, such as the keyboard decoder, display, scratch-pad memory, and processor. A PC Card storage device driver determines the power that it uses when the device is in the suspend state. The processor might take as long as 100 milliseconds to wake up from this state.

An H/PC switches to the suspend state when the following events occur:

  • The user selects the Suspend command.
  • The device detects a critical-power condition.
  • The activity timer performs a time-out.

Windows CE uses an activity timer to gauge whether a user is actively using a device. The timer counts down while the device is in the on state. When the timer reaches zero, the H/PC switches to the suspend state. The user can set the maximum value of this timer, in seconds. Two events reset the timer to its maximum value: a key press or release or a touch event. When the timer reaches five seconds, the H/PC sounds a warning to alert the user that it is about to suspend operation. The operating system does not notify applications when it enters the suspend state because most applications are not affected by this transition. When the device resumes operation, applications also resume operation as if they had been continuously running.

Programming the Suspend State

Applications generally do not run while an H/PC is in the suspend state. However, several functions can alter the time at which an H/PC suspends itself. The following table shows functions that you can use to reset activity times or to set timers and events that can switch an H/PC from the suspend state to the on state.

Function
Description
CeRunAppAtTime | Sets a timer or runs an application at a specified time.
WaitCommEvent | Waits for a communications event to occur. Serial, Infrared Data Association (IrDA), or PC Card storage devices can return EV_POWER when the device resumes operation.

If an application uses the Sleep function, it does not increment the elapsed time counter while the H/PC is in suspend state. It starts counting again when the H/PC resumes operation. The internal clock is not affected when the H/PC suspends operation. Though an application is not notified when a device enters the suspend state, the operating system does notify a device driver by calling a power-handler function. A device driver might use this notification to suspend operation of the device it controls, which may cause a device not to be available immediately after the device switches to the on state. For example, when a file stored on a PC Card storage device is open and the user tries to save the file before the PC Card is turned on, the system returns an error message.

On State

In the on state, an H/PC uses more power than in the dead or suspend states. Any time the display, keyboard, or touch screen are active, an H/PC is in the on state. When in the on state, an H/PC can switch between two processor modes: full speed and idle. In full-speed mode, the processor runs at normal operating frequency. In idle mode, the internal processor clock stops, and the processor uses little power. Peripherals and DRAM may be on or off. The processor can enter and exit this state in approximately 10 milliseconds. An H/PC switches to the on state when one of the following events take place:

  • A user presses the On button.
  • A user triggers an alarm event.
  • A user performs a warm or cold boot.
  • A user changes the battery.

In the on state, the default mode is full speed. An H/PC switches from full-speed mode to idle mode when all processes are idle. Switching to idle mode is transparent to the user and most applications because the system continues to process interrupts, including the time-slice interrupt.

Programming in the On State

When an H/PC is in the on state, some applications may prevent the operating system from switching an H/PC to the idle mode. These applications retain control by using idle loops or by using functions that do not let the operating system block operation. All applications can enhance power management by using functions that let the operating system block a return to the application. To accomplish this, use the GetMessage function, rather than the PeekMessage function, because GetMessage lets the system block a return to the application, and PeekMessage does not. Letting the operating system retain control allows it to determine when the system is inactive so that it can select the most efficient operating state for the H/PC.

If you are programming a power-critical application, use the GetPowerStatusEx function to determine the amount of power remaining on an H/PC. This function returns a variety of information regarding power status, including the amount of remaining power, how long the current charge will last, and recharging status.

Resuming Operation, Rebooting, and Resetting

Resuming device operation from the on-state idle mode or the suspend state does not alter the memory of an H/PC or change application settings. In contrast, rebooting or resetting an H/PC does alter memory and affect application operation. The following table shows the differences between these transitions.

Transition
Description
Wake up
or resume 		Transitions from the suspend state to the on-state full-speed mode. Wake up does not change memory or application settings.
Cold boot
or cold reset 		Resets an H/PC. All applications are terminated, the working memory is cleared, and the object store is cleared.
Power-on reset Transitions from a dead state to an on state. Power-on reset has the same consequences as a cold boot.
Warm boot
or warm reset 		Terminates all applications and clears working memory. The integrity of the object store is maintained.

The cold boot and power-on reset transitions occur when power is first applied to an H/PC or when all power is removed from an H/PC and then reapplied after one minute. Unless an H/PC uses nonvolatile memory, a user will have to load or reload applications after a power-on reset. Object store data is lost after a cold boot.

A warm boot occurs when the user presses the reset button on an H/PC. This button is placed in a pin-hole recess or under the battery cover to protect it from accidental activation. Users perform a warm boot only when the H/PC has stopped responding or has become unstable. A warm boot stops applications that are running and clears the memory used to execute applications. Memory used by the object store and file system is preserved.


Communications and Connectivity

One of the strengths of an H/PC is its ability to connect to and communicate with other computers and peripherals. This section discusses how to write applications that take advantage of these capabilities.


Programming the Built-in Serial Port

Some manufacturers supply only one universal asynchronous receiver-transmitter (UART) to control the built-in serial port and the IR port. To access the IR port on an H/PC with a shared UART, you must redirect communications by using the EscapeComm function.

To open and use the IR port on an H/PC with one UART for both ports

  1. Call the CreateFile function to open the built-in, nine-pin serial port, usually “COM1:”.
  2. Call the EscapeCommFunction function with the handle obtained from CreateFile as the hFile parameter and SETIR as the dwFunc parameter.

    The SETIR flag indicates that the serial port is to be set to IR mode. EscapeCommFunction returns TRUE if an IR-capable port has been selected.

  3. Fill the DCB structure with the existing communication port settings by calling the GetCommState function.
  4. Configure the communication port by assigning values to the members of the DCB structure and calling the SetCommState function.
  5. Set the timeout values for read/write operations on the port with a call to the SetCommTimeouts function.
  6. Call the ReadFile and WriteFile functions on the device handle returned from CreateFile.

Windows CE supports Windows Sockets (Winsock) and the IR extensions to Winsock (IrSock) for developing communications applications.

Note The Windows CE CreateFile function requires a colon appended to the device name. In most cases, “COM1:” designates the built-in serial port on an H/PC.


Programming with a PC Card

adding extra memory to an H/PC. This section discusses how to access files on PC Card storage devices.


Programming a PC Card Serial Device

Windows CE detects a PC Card when it is inserted or if it is in place when a user starts an H/PC. The OS automatically loads the device drivers needed to use the card when it detects a supported PC Card.

All active, top-level windows receive a WM_DEVICECHANGE message from the OS when a PC Card is first inserted. To determine if a PC Card was inserted before the application started running, call the EnumPnpIds function. It returns a double-0-terminated list of 0-terminated Plug and Play identifiers of all active PC Cards. Generally, the list returned from EnumPnpIds contains only one member because most H/PCs have only one PC Card slot.

Alternatively, Telephony API (TAPI) applications can call the LineGetDevCaps function to determine if a particular modem is inserted into the PCMCIA slot on an H/PC. The devSpecific member of the LINEDEVCAPS structure returned from LineGetDevCaps contains the device type and indicates whether or not it is active.


Programming a PC Card Storage Device

A PC Card storage device is assigned the folder name Storage Card in Windows CE. To create, copy, or delete files on the PC card, open the Storage Card folder. From there you can create, copy, or delete files. A user accesses files on a PC Card storage device by double-tapping on the My Handheld PC icon, which brings up the Windows CE Explorer window. The user then chooses the Storage Card folder.

The following code example shows how to a file named Testfile under \Storagecard\Testdir.

HANDLE   hFile;
DWORD    dwFileLen;
char         szText[]="This is a test file.";

if (CreateDirectory(TEXT("\\Storage Card\\testdir"), NULL))
{
   hFile = CreateFile(TEXT("\\Storage Card\\testdir\\test.txt"),
      GENERIC_WRITE|GENERIC_READ,      //I need read and write access.
      FILE_SHARE_READ,                 //Allow read access for others.
      NULL,                            //Security attributes
      CREATE_ALWAYS,                   //Always create a new file.
      0,                                   //File attribute
      NULL);
   WriteFile(hFile, szText, strlen(szText), &dwFileLen, 0);
   CloseHandle(hFile);
}

Note The actual path for the PC Card storage device is \Storage Card, but due to the special character inside the quotes, you need to assign the path as \\Storage Card.


Printing from an H/PC

Because Windows CE includes printing support, H/PC applications may enable printing. Use the PrintDlg function to provide printing capability in your applications. PrintDlg in Windows CE 2.0 is the same as it is on Windows-based desktop platforms, with one exception. Because Windows CE 2.0 does not support the Print Setup dialog box, the members associated with it do not exist in the Windows CE PRINTDLG structure.

Because the Print Setup dialog box is not supported in Windows CE 2.0, you cannot set page ranges or specify the number of copies to print. You must print the entire document or the currently selected portion of the document, and you can print only one copy at a time. However, Windows CE 2.0 does support some page setup functionality. In Windows CE 2.0, two members have been added to the PRINTDLG structure: rcMargin and rcMinMargin. The rcMargin member specifies the widths of the left, top, right, and bottom margins; the rcMinMargin member specifies the minimum allowable widths for those margins.

In contrast, Windows CE 2.10 does not support PrintDlg. However, it does support the PageSetupDlg function. The Page Setup dialog box lets a user set the attributes of a printed page. Create your own Print dialog box using the dialog template.


Using the TNEF API

Windows CE 2.10 contains several encoding and decoding options, including the ability to package and parse meeting request information to and from the Transport-Neutral Encapsulation Format (TNEF).TNEF is a Mail API –defined format that encapsulates MAPI message properties inside a single binary stream. To preserve MAPI properties, a sending application uses TnefBuildInfo to encode a MAPI message into a TNEF stream. A receiving application uses TnefGetInfo to decode the stream and reconstruct the original MAPI message. Currently, the transport DLL that ships with allows applications to retrieve attachments and meeting-request properties.

The TNEF API also provides a variety of functions to package messages, files, and other information for transfer over the Internet. The following table shows the function you can use to…

Function
Description
TnefEncodeBuffer
TnefEncodeFile
TnefDecodeBuffer
TnefDecodeFile
TnefConvertToUnicode
ModifiedUTF7ToUnicode
UnicodeToModifiedUTF7

TnefEncodeBuffer and TnefEncodeFile functions take binary data and translate it into 7-bit data. A server can then send this information over the Internet, and the receiving application can decode this information, using TnefDecodeBuffer and TnefDecodeFile. These functions translate to and from Base64, Quoted-Printable, and UUENCODE formats. Once you decode the buffer or file, you can translate the data into Unicode using TnefConvertToUnicode. To translate directly between Modified UTF7 format and Unicode, use ModifiedUTF7ToUnicode and UnicodeToModifiedUTF7.

Note These functions begin with the letters TNEF because they appear in the TNEF API; they are not directly related to the TNEF format.

The following code example shows how to use TnefEncodeFile.

BOOL SendAttFile (HANDLE hMail, MailMsg mm)
{
  MailAtt mAtt;                       // The MailAtt structure

  // Check if there are any attachments to the mail.
  if (!(mm.dwFlags & MAIL_STATUS_ATTACHMENTS))
    return FALSE;

  mAtt.uiAttachmentNumber = 1;

  while (MailGetAttachment(hMail, &mm, &mAtt) != -1 )
  {
    if (mAtt.szLocalName)
    {
      HANDLE hFile;                   // Handle to the encoded file
      LPTSTR lpszEncodedFile = NULL;  // Pointer to the encoded file
                                      //name

      // Encodes the attachment file
      if (!(lpszEncodedFile = TnefEncodeFile (
                                              mAtt.szLocalName,
                                              CODE_B64)))
      {
        return FALSE;
      }

      // Open the encoded file for reading.
      if ((hFile = CreateFile (
                              lpszEncodedFile,
                              GENERIC_READ,
                              FILE_SHARE_READ,
                              (LPSECURITY_ATTRIBUTES)0,
                              OPEN_EXISTING,
                              FILE_ATTRIBUTE_NORMAL,
                              (HANDLE)0)) != INVALID_HANDLE_VALUE)
      {
        // Insert code here for reading data from the encoded file and
        // then sending the data out.
        // ...
// Once the reading and sending data are done, close the file.
        CloseHandle(hFile);
      }

      // Delete the encoded file, and free the resource associated with
      // lpszEncodedFile.
      DeleteFile (lpszEncodedFile);
      LocalFree (lpszEncodedFile);
    }

    // Go to the next attached file.
    mAtt.uiAttachmentNumber++;
  }

  return TRUE;
}

The SendAttFile function checks to see if there are any attached files in the specified mail message. SendAttFile then encodes the attached files. SendAttFile also contains an area for implementing your own code to mail the encoded data to another application.

The following code example shows how to use TnefBuildInfo.

BOOL SendTNEFile (HANDLE hMail, MailMsg mm)
{
  HANDLE hFile;                     // Handle to the TNEF file

  TCHAR szTnefCorrelator[200];      // The szTnefCorrelator of the TNEF
                                    // structure
  LPWSTR lpszMsgType = NULL;        // Pointer to the message type

  TNEFINFO ti;                      // Pointer to the TNEFINFO structure
  MailNonIpmInfo* lpnii;            // Describes non-IPM data

  // Get mail message type.
  if (!(lpszMsgType = MailGetField (&mm, _T("Type"), FALSE)))
    return FALSE;

    // Check if the message contains schedule plus data.
    if (lstrcmp(lpszMsgType, _T("IPM.Schedule.Meeting")) != 0 &&
      lstrcmp(lpszMsgType, _T("IPM.Microsoft Schedu")) != 0)
  {
    LocalFree (lpszMsgType);
    return FALSE;
  }

  LocalFree (lpszMsgType);

  if (lpnii = HeapAlloc (mm.hHeap, 0,
              sizeof (MailNonIpmInfo) + 30 * sizeof (CEPROPVAL)))
  {
    DWORD dwIndex = 0,
          dwBufLen = 0;
    LPBYTE lpbBuf = NULL;

    int iPropIDs = 30;          // The number of property identifiers

    CEOID CeOid,                // The object identifier of the parent
                                   database
          CeOidMailMsg;         // Object identifier of the mail message
    CEOIDINFO OidInfo;          // Contains the mail message information
    CEPROPID rgPropId[30];      // The identifiers of the property value

    HANDLE hDataBase = INVALID_HANDLE_VALUE;
                                // The handle to the database that
                                // contains the mail message
    // Retrieves information about the mail message in the object store
    if (!CeOidGetInfo (mm.oid, &OidInfo))
      return FALSE;

    CeOid = OidInfo.infRecord.oidParent;

    // Insert code here to open the database that contains the mail
    // message.
    // hDataBase = ...

    lpnii->uiPropCount = iPropIDs;
    lpnii->szMessageClass = lpszMsgType;

    // Seeks the mail message record in the database
    if ((CeOidMailMsg = CeSeekDatabase (
                                        hDataBase,
                                        CEDB_SEEK_CEOID,
                                        mm.oid,
                                        &dwIndex)) != mm.oid)
    {
      return FALSE;
    }
    else
    {
      // Assign identifiers of the property value to rgPropId.
      // rgPropId = {...}

      // Reads properties from the current mail record
      CeOidMailMsg = CeReadRecordProps (
                                    hDataBase,
                                    CEDB_ALLOWREALLOC,
                                    &(USHORT)lpnii->uiPropCount,
                                    rgPropId,
                                    &lpbBuf,
                                    &dwBufLen);
    }

    // Close the database.
    CloseHandle (hDataBase);

    // Copy propvals into lpnii.
    memcpy (&(lpnii->propArray), lpbBuf, iPropIDs * sizeof (CEPROPVAL));

    LocalFree (lpbBuf);
  }
  else
    return FALSE;

  // Constructing szTnefCorrelator by using an object identifier
  wsprintf (szTnefCorrelator, _T("WCETnefCorrelator%lx"), mm.oid);

  if (GetTempPath (MAX_PATH, (LPWSTR)&ti.szTnefFileName) == 0)
    lstrcpy((LPWSTR)&ti.szTnefFileName, _T("\\"));

  lstrcat ((LPWSTR)&ti.szTnefFileName, _T("WCEMail.Tnef"));

  // Fill the TNEFINFO structure.
  ti.szTnefCorrelator = szTnefCorrelator;
  ti.wContentEncoding = CODE_B64;

  // Create the encoded TNEF file.
  if (!TnefBuildInfo (&ti, MailGetField (&mm, _T("Subject"), FALSE),
                     lpnii, NULL))
  {
    return FALSE;
  }

  // Open the TNEF file for reading.
  if ( (hFile = CreateFile (
                            (LPWSTR)&ti.szTnefFileName,
                            GENERIC_READ,
                            FILE_SHARE_READ,
                            (LPSECURITY_ATTRIBUTES)0,
                            OPEN_EXISTING,
                            FILE_ATTRIBUTE_NORMAL,
                            (HANDLE)0)) != INVALID_HANDLE_VALUE)
  {
    // Insert code here for reading data from the TNEF file, and then
    // sending the data out.
    // ...

    // Once reading and sending the data are done, close the file.
    CloseHandle(hFile);
  }

  // Delete the TNEF file.
  DeleteFile ((LPWSTR) &ti.szTnefFileName);

  return TRUE;
}

The SendTNEFile function checks whether a mail message contains non-IPM data from Schedule+. If the mail message does contain this information, SendTNEFile encodes the mail message and sends out the encoded file.

You can use both of these samples in your implementation of the TransportSend function in Transport.dll. ›


Registry Settings

Windows CE 2.10 comes with a variety of options for mail transport services. These options include the following registry settings.

  • HKEY_LOCAL_MACHINE\PMail\ServiceLibs\[ServiceType]
    \NewHierarchy

    If an application or user sets this DWORD key as a nonzero value, every service of this type is allocated a separate folder hierarchy in the message store. These folder hierarchies have the same name as the corresponding mail service name. If this key is 0, services of this type use the Mailbox hierarchy. The OS writes this registry key as 0 by default.

  • HKEY_LOCAL_MACHINE\PMail\ServiceInfo\[ServiceName]
    \InboxOnly

    If an application or user sets this DWORD key as a nonzero value, the client operates only on the Inbox folder subtree of the specified service. If this key is 0, the client operates on the whole folder hierarchy. The system writes this registry key as 0 by default. A Service DLL that allows a user to specify this option must implement the TransportGetInboxId function.

Note Windows CE 2.10 ignores the GrabRead registry option. When Windows CE 2.10 reads a message from a service, the message body is always placed in the local store.


Developer's Tools

Developer’s Tools

An H/PC supports a wide variety of programming tools for different languages. Currently, Microsoft provides toolkits, remote tools, and emulators.

Windows CE Toolkits for the H/PC

A toolkit is a set of Help files, programming tools, samples, and other routines designed to help you write applications in a specific programming language. Microsoft toolkits for Windows CE are integrated into the Microsoft® Visual Studio™ . You can access a toolkit through the integrated development environment (IDE). Portions of the toolkit may also be accessed separately through the Start menu. The following table shows the toolkits currently available for programming an application for an H/PC.

Toolkits
Microsoft® Windows® CE Toolkit for Visual C++® 5.0 | H/PC 2.0, H/PC 1.0
Microsoft® Windows® CE Toolkit for Visual Basic® 5.0 | H/PC 2.0
Microsoft® Windows® CE Toolkit for Visual Basic® 6.0 | H/PC 2.0, H/PC 3.0


H/PC Remote Tools

A remote tool is an application that allows you to access a remote computer as though it were an H/PC device. Although they are included in the Windows CE toolkits, the remote tools are considered to be separate applications. The following table shows the remote tools.

Remote tool
Description
Remote CE Heap Walker | Enables you to view detailed information about heap identifiers and flags for processes that are running on a remote platform. The Windows CE Heap Walker is a useful tool to determine if an application has memory leaks.
Remote CE Object Viewer | Displays a hierarchical view, on the desktop computer, of the Windows CE object store. The Remote Object Viewer enables you to transfer objects between the emulation object store and the remote platform.
Remote CE Process Viewer | Displays a graphical view of Windows CE process and thread characteristics. The Process Viewer enables you to view memory usage and search for memory leaks.
Remote CE RegEdit | Manages remote platform registry entries from the desktop computer.
Remote CE Spy | Displays a graphical view, on the desktop computer, of Windows CE system processes, threads, windows, and window messages running on the remote platform.
Remote CE Zoom | Captures an image from the remote platform and displays it on the desktop computer.

For more information, see the Windows CE Toolkits H/PC Emulator.

The Microsoft ®Windows® CE Platform SDK, Handheld PD Edition, Version 2.0 includes an emulator. The emulator acts as a virtual H/PC on your desktop computer. Like the remote tools, you can use the emulator through the IDE, or you can access it through the Start menu. The Emulator comes with a virtual registry editor.


Programming H/PC Controls

Windows CE 2.10 contains two unique controls: the Rich Ink control and the HTML control. The following section discusses how to create and use these controls.

Programming a Rich Ink Control

A Rich Ink control enables a user to write and draw on the touch-sensitive screen of an H/PC with a stylus or other pointing device. A Rich Ink control provides a convenient means for applications to accept input from a user without using a keyboard. For a user, taking notes or drawing sketches with a Rich Ink control is very much like writing or drawing on paper.

In addition to capturing images, a Rich Ink control provides powerful editing and formatting capabilities. For example, when a user deletes a word from handwritten notes on the screen, the control automatically closes the resulting word gap. An application can use a Rich Ink control in the following ways:

  • An electronic form application can accept a user’s handwritten signature.
  • A calendar application with an embedded Rich Ink control can allow a user to jot down a “To Do” list for a selected date.

Once a user has added data using a Rich Ink control, you can translate that data into an RTF or text file.


Creating a Rich Ink Control

A Rich Ink control is neither a windows control nor a common control. Like an HTML control, a Rich Ink control is unique to Windows CE. However, the process for creating a Rich Ink control is similar to the process for creating a common control.

To create and embed a Rich Ink control in your application

  1. Call InitCommonControls to load the common control dynamics-link library (DLL).
  2. Call InitInkX to load and initialize Rich Ink control.
  3. Call CreateDialog to instantiate a dialog box with a custom ink control.

– Or –

  1. Call InitCommonControls to load the common control DLL.
  2. Call InitInkX to load and initialize Rich Ink control.
  3. Call CreateWindow and specify the class name as WC_INKX.

The EReceipt and InkControl sample codes provide two examples of the implementation.


Using A Rich Ink Control

After initialization, a Rich Ink control communicates with the calling application using the standard Windows CE messaging system. Specifically, the control performs the following tasks:

  • Sends the IM_SHOWCMDBAR message to the Rich Ink control to show or hide the command bar.
  • Sends the IM_GETDATALEN, IM_GETDATA, and IM_SETDATA messages between the Rich Iink control and the application to transmit inking data, such as notes or a sketch.
  • Sends the IM_REINIT message to the Rich Ink control to erase all the content from the control.
  • Sends the standard EM_GETMODIFY and EM_SETMODIFY messages to the Rich Ink control to determine if the Rich Ink content has been modified and to set the modification flag in the control, respectively.


Converting Rich Ink Data

The Rich Ink control stores data in an internal .PWI file format.

To convert .PWI data to a RTF or text file format

  1. Load the RichInk .dll

    2.Create a RichInk control

  3. Send an EM_STREAMIN message with the SendMessage function to stream the RichInk data in from a memory block
  4. Send an EM_STREAMOUT message with SendMessage to determine the size of the converted text.
  5. Allocate memory for the converted text
  6. Steam the converted text to the memory you allocated

The following code example shows how to


Programming an HTML Viewer Control

An HTML Viewer control provides a viewer that can display HTML text and embedded images on an H/PC. The HTML viewer also provides the features required to implement the Microsoft® Pocket Internet Explorer internet browser and a Help engine.

You can also create other viewers based on an HTML viewer control. An HTML source can include references to other sources, which might provide different types of data. If the application determines that some of the data it retrieves is of a type other than HTML, it can invoke another type of viewer to display that data.

To use an HTML Viewer control, you must include the Htmlctrl.h header file in your application. Additionally, you must either link your application with the Htmlview.dll, or load the HTML viewer DLL by calling the LoadLibrary function. When you call LoadLibrary, pass Htmlview.dll as the lpLibFileName parameter.


Creatingan HTML Viewer Control

Before you can create an HTML viewer control, you must register it by calling the InitHTMLControl function. You create an HTML Viewer control by specifying DISPLAYNAME in the lpClassName parameter to the CreateWindow function.

To create the HTML Viewer control

  1. Load the HTML Viewer DLL by calling the LoadLibrary function.

    Specify Htmlview.dll in the lpLibFileName parameter.

  2. Register the HTML Viewer control class by calling the InitHTMLControl function.
  3. Create a window for the HTML Viewer control by calling the CreateWindow function.

    Specify DISPLAYNAME in the lpClassName parameter.

Note When you call the LoadLibrary and CreateWindow functions, the library or class name has to be a Unicode string. Use the TEXT macro to cast a string as Unicode, for example, TEXT (“Htmlview.dll”).

The following code example shows how to create an HTML Viewer control.

#define DISPLAYCLASS  TEXT("DISPLAYCLASS")

BOOL g_bMakeFit = TRUE;          // DTM_ENABLESHRINK Shrink-enable flag
TCHAR const c_szHTMLControlLibrary[] = TEXT("htmlview.dll");
HINSTANCE g_hInstHTMLCtrl;       // HTML Control Viewer instance
HINSTANCE hInstance;             // Application instance
HWND m_hwndHtml;                 // Handle to HTML DISPLAYCLASS window

g_hInstHTMLCtrl = LoadLibrary (c_szHTMLControlLibrary);

InitHTMLControl (hInstance);

LRESULT WndProc (HWND hwnd, UINT msg, WPARAM wp, LPARAM lp)
{
  switch (message)
  {
    case WM_CREATE:
    {
      DWORD dwStyle = WS_CHILD | WS_VISIBLE | WS_VSCROLL |
                      WS_CLIPSIBLINGS;

      m_hwndHtml = CreateWindow (DISPLAYCLASS,
                                 NULL,
                                 dwStyle,
                                 rc.left,
                                 rc.top,
                                 rc.right - rc.left,
                                 rc.bottom - rc.top,
                                 hWnd,
                                 (HMENU)IDC_HTMLVIEW,
                                 g_hInst,
                                 NULL);

      SetFocus (m_hwndHtml);
      PostMessage (m_hwndHtml, DTM_ENABLESHRINK, 0, g_bMakeFit);
      break;
    }
    .
    .
    .
  }
}


Displaying an HTML Document

Once you create an HTML viewer control, you can use the control to display an HTML document.

To display an HTML document

  1. Clear the current contents of the HTML viewer control by sending it a WM_SETTEXT message.
  2. Load an HTML document and copy the document text to the control by sending the control a series of DTM_ADDTEXT messages for ASCII or DTM_ADDTEXTW messages for Unicode.
  3. When document processing is complete, send the control a DTM_ENDOFSOURCE message.
  4. Process any NM_HOTSPOT notifications that are sent by the control when a user taps a link or submits a form.
  5. For each NM_INLINE_IMAGE notification received from the control, load the image so that the HTML Viewer control will display the image-loading icon.
  6. After the image has loaded successfully, send the control a DTM_SETIMAGE message that contains the bitmap handle (HBITMAP) of the image to display.

    If the image does not load successfully, send a DTM_IMAGEFAIL message, which indicates to the control that it should display the broken-image icon.

  7. For each NM_INLINE_SOUND notification received from the control, load the sound, and then play it the number of times indicated in the dwLoopCount parameter.

Pocket Internet Explorer is an example of an application that uses the HTML Viewer control. The application, Webview.exe, links with the DLL that provides the HTML Viewer control, Htmlview.dll. The application provides the user interface, retrieves the data from each Uniform Resource Locator (URL), and interprets the data.

The following illustration shows how the application interacts with the HTML Viewer control.


Applications Included with an H/PC

The applications that are described in this section are separate from the Windows CE OS and that come with every H/PC. The following list describes the included applications on an H/PC that expose APIs or contain controls discussed in other sections of the SDK:

  • Pocket versions of the Microsoft® Office office suite applications

    The Handheld PC Pro Edition software includes the Microsoft® Pocket Excel spreadsheet, the Microsoft® Pocket Word word processor, the Microsoft® Pocket PowerPoint® presentation graphics program, and the Microsoft® Pocket Access database.

  • HTML Help for Windows CE

    HTML Help for Windows CE lets users access your Help files on a H/PC.

  • Microsoft® Pocket Outlook

    Pocket Outlook provides tpersonal information manager (PIM) features, including Calendar, Contacts, Tasks, and Inbox. Pocket Outlook exposes the Inbox and Contacts APIs.

  • Remote Networking

    Remote Networking combines the capabilities of the following two Windows-based applications:

    ·H/PC software uses dial-up networking for connecting to a Remote Access Service (RAS) server. Unlike Dial-Up Networking on Windows-based desktop platforms, Remote Networking allows an H/PC to be a dial-up client, but not a server. An H/PC supports connections to RAS servers using PPP with TCP/IP as the underlying network protocol.

    ·H/PC software uses direct cable connection (DCC) to establish a direct serial connection between an H/PC client and a Windows-based desktop computer host. DCC allows a client to share the resources of a host computer. DCC uses PPP to establish a data-link-level connection to run network protocols and transport layer protocols. Determine the state of the DCC connection by using the RAS API set.

  • Terminal

    Windows CE Terminal uses a serial cable or modem connection to connect an H/PC with a desktop computer to transfer files or act as a remote terminal. Windows CE Terminal can also connect an H/PCto a remote Bulletin Board System (BBS). Although Windows CE Terminal does not support file transfer protocols, you can use it to cut and paste information from a BBS.

    You can use Terminal to configure modems and set dialing properties. It also allows the following terminal emulation:

    • Generic TTY
    • VT-100/ANSI
    • PC Link

In addition to these bundled applications, some manufactures may include software that allows a user to connect a modem to theserial port on an H/PC.


Designing a User Interface for an H/PC

Because the Handheld PC (H/PC) is designed to be a companion to a Windows-based desktop computer, the shell and core applications for the H/PC look like their counterparts on Windows-based desktop platforms. This similarity provides a solid base of potential customers when a new H/PC application is introduced.

On the OS for the H/PC, users recognize elements made familiar by Windows desktop platforms: a desktop and a taskbar, windows and dialog boxes, menus and controls. These and other elements allow the user to control the H/PC environment.

When designing an H/PC application, all of the principles of good user interface design discussed in the previous chapter apply.


Working with the Desktop and Taskbar

The desktop forms a visual background for all operations. It provides a familiar interface for accessing documents, launching applications, switching between tasks, browsing the file system, and performing other services. The components of the H/PC desktop include a work area, a taskbar, and application shortcuts or icons, such as the Recycle Bin and Inbox. Though you cannot programmatically control the appearance of the desktop, it is important to understand its specifications so that you can design your interface accordingly. The following illustration shows the desktop of the H/PC shell.

The shell for the H/PC is similar to other Windows desktops. It contains file, folder, and shortcut icons that can be positioned anywhere on the desktop. Unlike other Windows-based platforms, however, the H/PC has a virtual border around its desktop to prevent icons from being fully obscured by the screen edge or taskbar. The desktop does not permit users to position an icon beyond the boundaries defined by the following rectangle coordinates:

(0,0, CX –16, CY –16)

Additionally, the browser in the H/PC software is integrated with Pocket Internet Explorer, which means that it contains two views: an HTML view to display Internet content and a File view to display the contents of folders. The browser assumes the appropriate view, depending on how it was launched. If it is launched by opening a folder, it assumes the File view. If it is launched by pointing to a URL, it assumes the HTML view. Each view in the browser contains it own toolbar. The File view toolbar contains controls similar to the Windows Explorer toolbar. The HTML toolbar contains controls similar to the Internet Explorer toolbar.

The taskbar is used to switch between or minimize open windows and to access global commands and other frequently used objects. It contains a Start button, window buttons, and a status area. It also contains a Desktop button that provides quick access to the desktop from any application. Because H/PC applications do not have title bars, users identify a running application primarily by the icon and text displayed on its taskbar button. The following illustration shows the H/PC taskbar.

By default, the taskbar is the top window in the H/PC shell. When fully displayed, the taskbar is 26 pixels high and either 480 or 640 pixels wide, depending on the resolution of the display. The taskbar in the shell for H/PC 2.0 supports autohide functionality. While hidden, the taskbar is 5 pixels tall. When a user hides the taskbar, a notification is sent to all applications that the usable vertical screen is increased by 21 pixels. To reactivate a hidden taskbar, each H/PC touch screen contains a 2.5 mm tap region around all four edges of the display. This, combined with the height of the taskbar, provides a generous tap region for activating the taskbar.

The H/PC shell taskbar also contains the following elements:

  • A Start menu

    The Start menu has two components: the main menu and cascading menus. The main menu has a maximum height of 240 pixels, the height of the display. Thus, the menu displays only the number of items that can fit into this region. If the contents exceed this number, the menu displays as many items as possible in alphabetical order. The width of the main menu cannot exceed 200 pixels. Any menu items wider than 200 pixels are cropped. The cropped text is replaced with ellipses.

    Cascading menus are also displayed in alphabetical order. They have a maximum height of 240 pixels. If the number of items displayed exceeds the height of the screen, the menu adopts a multiple-column mode and shows the remaining menu items in the adjacent column.

    Like other Windows-based platforms, main and cascading menus use the 16x16-pixel icon associated with the menu item. Items that cascade to additional menus are appended with a triangular arrow.

  • Window buttons

    The H/PC displays window buttons for all open parent windows. Any open window can be minimized by tapping its Window button on the taskbar. Window buttons are 23 pixels tall; button width is equal to the width of the available taskbar tray area divided by the number of buttons. The maximum button width is one-third of the available tray area. The minimum button width is 26 pixels. All Window buttons display an icon and caption. The icon is 16x16 pixels, so the window button is always able to display the entire icon. The caption truncates as the width of the button decreases in size. Activated window buttons do not have bold captions.

  • A Desktop button

    The Desktop button provides quick access to the desktop. When the button is pressed, it brings the desktop forward and into focus, effectively minimizing any open application. When the desktop is in the foreground, the Desktop button appears depressed to denote that the desktop is currently displayed. Pressing the Desktop button while the Desktop button appears depressed causes the previously active application to reactivate. The Desktop button is 23x22 pixels, the size of the standard toolbar button, and is located on the right edge of the taskbar.

  • A notification area

    You can add a status indicator to the notification area of the taskbar. Indicators are represented by graphics supplied by your application. They contain information that is global or that needs monitoring by the user when working with other applications. When adding a status indicator to the taskbar, provide a pop-up window that displays additional information or controls for the object when the user taps the indicator icon. Also provide a status indicator that displays commands for the object when the user performs an ALT+Tap action on the indicator icon. Carry out the default command defined in the pop-up menu when the user double-taps the indicator icon. Display a ToolTip that indicates what the status indicator represents, and provide the user with an option not to display the status indicator.

    Status indicators are 16x16 pixels, except for the clock, which occupies a fixed space. All status indicators are placed 3 pixels to the left of the clock with 0 pixels between each indicator. If you add a status indicator to the taskbar, you must define its access method. The methods supported by the taskbar include the tap-down action, tap-up action, double-tap action, and ALT+Tap.


Designing Windows and Dialog Boxes

Windows enable the user to view and interact with data. Consistency in window design is important because it enables users to easily transfer their skills and focus on tasks, rather than learn new conventions.

The OS for the H/PC supports most common Win32 application programming interface (API) window functions; however, due to constraints posed by the H/PC screen size, the system is designed for full-screen applications. Windows can be moved around the screen, but they cannot be resized by users. It is possible to create smaller windows for applications, such as a calculator, that can be used while another application is displayed, but most applications should use the entire screen.

While all H/PCs conform to a hardware specification standard, some manufacturers offer features that extend functionality. These additional features include an expanded LCD screen, 640x240 or 640x480 pixels in size. The expanded screen allows applications to display up to 80 characters per line at an easily readable character size, using half-height or full-size VGA graphics resolution. This means the font aspect ratio is similar to a desktop computer and eliminates the feeling that the characters are squeezed onto the screen.

You can take advantage of the expanded screen size by designing applications capable of displaying a full-width view of documents and images. This minimizes the amount of scrolling needed and makes applications easier to use. Programming applications for 640x480 screens does not necessarily require that separate code be maintained for H/PCs with 480x240 screens. Create application windows using default values that indicate full-screen size regardless of its dimensions. Position objects using relative, as opposed to absolute, coordinates.

Primary windows in the OS for the H/PC are similar to all other standard windows. However, unlike other windows, H/PC primary windows do not contain title bars. Instead, they contain a command bar.

Dialog boxes differ from primary windows in that they do not have taskbar window buttons, so users cannot switch between open dialog boxes by tapping a button on the taskbar. Additionally, dialog boxes obtain or display supplemental information related to objects displayed in a primary window.

Dialog boxes must be smaller than primary windows in order to differentiate between windows. Windows-based desktop platforms use a bold system font when displaying dialog box text. Windows CE uses the non-bold system font when displaying text, except for text on a light gray background. The default system font for Windows CE is Tahoma, 9 point.

Note If you are developing Windows CE–based applications under emulation, and you want to lay out windows and dialog boxes that look the same on your desktop computer as they look on an H/PC, use Tahoma.fon.

The OS for the H/PC supports common dialog boxes, which provide a familiar way for users to perform standard tasks common to many applications. Windows CE supports the Color, Print, Open, and Save As dialog boxes, which function the same way as in Windows 95, with the following exceptions:

  • The shell for the H/PC 2.0 implements the Print dialog box as a simple printing interface with one common dialog box. The Print dialog box enables the user to choose a printer type, printer port, the number of copies, print range, orientation, and margin settings. Windows 95 and Windows NT provide a Print dialog box, a Page Setup dialog box, and a Print Setup dialog box to cover these operations. The following illustration shows the Print dialog that appears in the shell for the H/PC 2.0.

  • The H/PC 2.0 Font dialog box is a shared dialog box that contains a default font option and color list. The following illustration shows the Font dialog box that appears in the shell for H/PC 2.0.

Common dialog boxes are not movable and are always centered vertically and horizontally on the screen. They always display the Help button.


Choosing Menus and Controls

H/PC applications can use all of the standard menus and controls available in Windows CE.


Receiving User Input for an H/PC

The OS for the H/PC supports both keyboard and stylus input. It does not support a mouse, and therefore does not have hover capability. The H/PC keyboard layout resembles a standard desktop computer keyboard, but most H/PC keyboard devices do not include the following keys:

  • INSERT
  • NUM LOCK
  • PAUSE
  • PRINT SCREEN
  • SCROLL LOCK
  • Function keys

The OS for the H/PC supports the WINDOWS key, but Microsoft does not require hardware platforms to include it. Therefore, avoid writing applications that require users to use this key.

When the user touches the screen with the stylus, the input focus moves to the object under the stylus. If the object is a button, it displays its pressed appearance. If the user moves the stylus off the control without lifting the stylus from the screen, the control returns to its original state. Moving the stylus back over the control while the stylus is still touching the screen returns the control to its pressed state. The command associated with the control is only activated if the user lifts the stylus from the screen while the stylus is touching the control. If the stylus is not on the control when the user lifts it, no action occurs. If the user touches the screen with the stylus on an object that can be dragged, and then moves the stylus while still touching the screen, the object moves with the stylus.

The conventions for selection, using a stylus on an H/PC are the same as the standard Windows conventions for selection using a pen or mouse. The OS for the H/PC supports standard drag-and-drop operations, using the stylus. It does not support non-default drag-and-drop operations, however, which are the right mouse button drag-and-drop operations on desktop platforms.

The OS for the H/PC also supports third-party handwriting-recognition applications. See the Windows Interface Guidelines for Software Design for implementation conventions.


Providing Help

Users can access Help in the H/PC shell either by selecting the Help command on the Start menu or by tapping a Help (?) button included on a window command bar. This Help button looks similar to the What’s This? button in Windows 95 and Windows NT, but it functions differently. The What’s This? button activates a Help mode in which the user can select a field about which to receive information. In the H/PC shell, the Help (?) button brings up the Help contents for the current window.

When creating a Help system for an application, follow these guidelines:

  • Use ALT+H as the shortcut key for accessing Help.
  • Write your Help file in HTML.
  • Create each topic as a text file with an .htp extension.
  • Create your contents page as a text file also, but save it with an .htc extension.


H/PC Enumerations

This section includes reference entries for the enumerations supported on the Handheld PC.


INETENCODE

This enumeration identifies a Multipurpose Internet Mailing Extension (MIME) encoding type.

At a Glance

Header file: | Tnefapi.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

typedef struct enum {
CODE_NONE = 0,
CODE_UU,
CODE_B64,
CODE_QP
CODE_QPH,
} INETENCODE;

Values

CODE_NONE
Specifies no encoding or decoding.
CODE_UU
Specifies the UUEncode format.
CODE_B64
Specifies the Base 64 format .
CODE_QP
Specifies the body or file attachments is in quoted printable.
CODE_QPH
Specifies the header is in quoted printable format.

Remarks

A transport uses this enumeration to specify how to encode or decode a file or buffer.

See Also

TnefDecodeBuffer, TnefDecodeFile, TnefEncodeBuffer, TnefEncodeFile


H/PC Pro Mail Store API

This section is a reference for the H/PC Pro Mail Store API. It includes reference entries for all the mail functions supported on Windows CE.


MailFirstEx

This function, an extension of MailFirst, retrieves the first of a specified type of message from a folder in the message store and operates in a multiple folder hierarchy environment.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL MailFirstEx (HANDLE hMail, MailMsg* pmm, FID* pfid,
FID* pfidTarget);

Parameters

hMail
[in] Handle to the mail context. The MailOpen function creates this handle.
pmm
[in/out] Pointer to the MailMsg structure. The dwFlags member of MailMsg determines what type of message this function should retrieve and how much of the message to return.

This function returns the specified message in MailMsg. The following message flags determine how much of the message this function retrieves:

MAIL_GET_FLAGS
The MailGetEx function returns only the flags and the object identifier, including the dwMsgId, dwFlags, dwMsgLen, wBodyLen, and ftDate MailMsg members. MAIL_GET_FLAGS also instructs MailGetEx to return the pfid and pfidTarget parameters.

MailGetEx does not allocate any memory for the message body.

MAIL_GET_BODY
MailGetEx loads the entire message into memory, and creates and allocates memory from a private heap for the message.

If neither of these flags is set, this function retrieves only the message header and allocates memory from the private heap.

pfid
[in/out] Pointer to the folder identifier of the folder to search in. This function ignores this parameter if the MAIL_FOLDER_ANY flag is set in the dwFlags member of MailMsg. If you set the MAIL_FOLDER_ANY flag, pfid returns the message folder identifier of the first message found that matches the description of the flags set in MailMsg.
pfidTarget
[in/out] Pointer to the target folder identifier of a Copy or Move command. This parameter is only valid if the MAIL_STATUS_MOVE or MAIL_STATUS_COPY flags are set in the dwFlags member of the MailMsg structure. Set pfidTarget to NULL if you do not need the target folder identifier.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function MailError or MailErrorMsg.

Remarks

Once this function has retrieved a message, you can modify the values returned in MailMsg. However, changing the values of MailMsg does not affect the message store until a call to the function MailUpdateEx reinserts MailMsg into the message store.

When using this function to search a folder for a message, treat any message that has the MAIL_STATUS_MOVE or MAIL_STATUS_COPY flag set as being located in the pfidTarget folder. This folder may differ from the folder indicated by fid, because a client can attempt to move or copy a message from one folder to another while the client is not connected to a mail server. If this happens, the OS sets the MAIL_STATUS_MOVE or MAIL_STATUS_COPY flag in MailMsg. MailUpdateEx saves the target folder, along with MailMsg, in the store. When the device connects to the mail server, the Inbox client performs the move or copy on the server, then uses MailUpdateEx to clear the existing flag from MailMsg and to set the value of fid to the new target folder.

To free memory allocated by this function, use the function MailFree.


MailGetEx

This function, an extension of MailGet, retrieves a mail entry from the message store and operates in a multiple folder hierarchy environment.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL MailGetEx (HANDLE hMail, MailMsg* pmm, FID* pfid,
FID* pfidTarget);

Parameters

hMail
[in] Handle to the mail context. This handle is created by the MailOpen function.
pmm
[in/out] Pointer to the MailMsg structure that contains the object identifier of the message to be retrieved. MailMsg also contains flags that determine how much of the message this function retrieves.

When this function returns, MailMsg contains the message retrieved from the message store. Setting the following two message flags in the dwFlags member of MailMsg determine how much of the message this function retrieves:

MAIL_GET_FLAGS
This function returns the oid, dwFlags, dwMsgId, dwFlags, dwMsgLen, wBodyLen, and ftDate parameters of MailMsg. MAIL_GET_FLAGS also instructs this function to return the pfid and pfidTarget parameters.

This function does not allocate any memory for the message body.

MAIL_GET_BODY
This function loads the entire message into memory and creates and allocates memory from a private heap for the message.

If you set neither of these flags, this function retrieves only the full message header and allocates memory from a private heap.

pfid
[out] Pointer to the folder identifier of the folder that the message is currently in.
pfidTarget
[out] Pointer to the target folder identifier of a Copy or Move command. This parameter is only valid if the MAIL_STATUS_MOVE or MAIL_STATUS_COPY flags are set in the dwFlags member of MailMsg. Set pfidTarget to NULL if you do not need the target folder identifier.

Return Values

TRUE indicates success. FALSE indicates failure. Call the function MailError or MailErrorMsg for extended error information.

Remarks

This function retrieves the mail message based on the value of the oid member the MailMsg.

Once this function has retrieved a message, you can modify the values returned in MailMsg. However, changing the values of MailMsg does not affect the message store until a call to the function MailUpdateEx reinserts MailMsg into the message store.

When using this function to retrieve a message, treat any message that has the MAIL_STATUS_MOVE or MAIL_STATUS_COPY flag set as being located in the pfidTarget folder. This folder may differ from that indicated by fid because a client can attempt to move or copy a message from one folder to another while the client is not connected to a mail server. If this happens, the OS sets the MAIL_STATUS_MOVE or MAIL_STATUS_COPY flag in MailMsg. MailUpdateEx saves the target folder, along with MailMsg, in the store. When the device connects to the mail server, the Inbox client performs the move or copy on the server, then uses MailUpdateEx to clear the existing flag from MailMsg and to set the value of fid to the new target folder.

To free memory allocated by this function, use the function MailFree.

Unlike MailGet, this function can retrieve messages longer than 32 KB characters.

See Also

MailPut, MailUpdate


MailGetFolderIdEx

This function, an extension of MailGetFolderId, retrieves the identification number of a mail folder from the message store and operates in a multiple hierarchy folder environment.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL MailGetFolderIdEx (HANDLE hMail, FID fidParent, FID* pfid, LPWSTR szName);

Parameters

hMail
[in] Handle to the mail context. This handle is created by the MailOpen function.
fidParent
[in] Folder identifier of the parent mail folder. If no parent folder exists, set fidParent to MAIL_FOLDER_NONE.
pfid
[out] Pointer to a folder identification number. If the folder name specified by szName exists in the message store, this function returns this parameter with the identification number associated with the name. This parameter does not return anything if the function fails.
szName
[in] Null-terminated string that contains the name of the mail folder being searched.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function MailError or MailErrorMsg.

See Also

MailGetFolderName


MailGetFolderNameEx

This function, an extension of MailGetFolderName, retrieves the name of a folder in the messages store and operates in a multiple-hierarchy folder environment.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL MailGetFolderNameEx (HANDLE hMail, FID* pfId, int* piLen
LPWSTR szName);

Parameters

hMail
[in] Handle to the mail context. This handle is created by the MailOpen function.
pfId
[in] Pointer to the folder identifier. The identifier is set by the MailPutFolderEx function.
piLen
[in/out] Pointer to the length, in characters, of the szName buffer. If the string is longer than (piLen –1), the string is truncated.

After calling the function, the value pointed to by piLen is the actual number of characters needed for the string being passed back to szName plus a terminating null character.

szName
[in] Null-terminated string that contains the name of the mail folder that corresponds to the specified identification number. If set to NULL, piLen returns the length of the folder name, in characters.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function MailError or MailErrorMsg.

Remarks

If the folder specified by szName does not exist, pfId returns the identifier of the next folder found. If no folders exist, pfId returns MAIL_FOLDER_NONE.

See Also

MailGetFolderIdEx


MailGetSvcIdEx

This function, an extension of MailGetSvcId, retrieves the object identifier (OID) of a mail message and operates in a multiple folder hierarchy environment.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL MailGetSvcIdEx (HANDLE hMail, MailMsg* pmm, FID* pfid);

Parameters

hMail
[in] Handle to the mail context. This handle is created by the MailOpen function.
pmm
[in/out] Pointer to the MailMsg structure that contains the service name and identifier of the mail entry. This function modifies and returns the oid, dwFlags, and wBodyLen members in this structure.
pfid
[in] Pointer to the folder identifier of the folder that contains the mail entry.

Return Values

TRUE indicates success. FALSE indicates failure. Call the function MailError or MailErrorMsg for extended error information.


MailNextEx

This function, an extension of MailNext, retrieves the next of a specified type of mail entry from the message store and operates in a multiple hierarchy folder environment.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL MailNextEx (HANDLE hMail, MailMsg* pmm, FID fid, FID fidTarget,
BOOL fDoAll);

Parameters

hMail
[in] Handle to the mail context. This handle is created by the MailOpen function.
pmm
[in/out] Pointer to the MailMsg structure. The dwFlags member of MailMsg is a combination of folder, status, and message flags. The folder flag determines which folder the message is in. The status flags determine what type of message this function should retrieve. The message flags determine how much of the message this function returns.
MAIL_GET_FLAGS
The MailGetEx function returns only the flags and the object identifier, including the dwMsgId, dwFlags, dwMsgLen, wBodyLen, and ftDate MailMsg members. MAIL_GET_FLAGS also instructs MailGetEx to return the pfid and pfidTarget parameters.

MailGetEx does not allocate any memory for the message body.

MAIL_GET_BODY
MailGetEx loads the entire message into memory and creates and allocates memory from a private heap for the message.

If neither of these flags is set, this function retrieves only the message header and allocates memory from the private heap.

pfid
[in/out] Pointer to the folder identifier of the folder to search in. This function ignores this parameter if the MAIL_FOLDER_ANY flag is set in the dwFlags member of MailMsg. The pfid parameter returns the message folder identifier.
pfidTarget
[in/out] Pointer to the target folder identifier of a Copy or Move command. This parameter is only valid if the MAIL_STATUS_MOVE or MAIL_STATUS_COPY flags are set in the dwFlags member of MailMsg. Set pfidTarget to NULL if you do not need the target folder identifier.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function MailError or MailErrorMsg.

Remarks

The flags of MailMsg must be set prior to each call to this function. This is because each call to MailFirstEx, MailGetEx, or this function returns the flags of the message as it is stored in the database.

Once this function has retrieved a message, you can modify the values returned in MailMsg. However, changing the values of MailMsg does not affect the message store until a call to the function MailUpdateEx reinserts MailMsg into the message store.

When using this function to search a folder for a message, treat any message that has the MAIL_STATUS_MOVE or MAIL_STATUS_COPY flag set as being located in the pfidTarget folder. This folder may differ from that indicated by fid, because a client can attempt to move or copy a message from one folder to another while the client is not connected to a mail server. If this happens, the OS sets the MAIL_STATUS_MOVE or MAIL_STATUS_COPY flag in MailMsg. MailUpdateEx saves the target folder, along with MailMsg, in the store. When the device connects to the mail server, the Inbox client performs the move or copy on the server, then uses MailUpdateEx to clear the existing flag from MailMsg and to set the value of fid to the new target folder.

To free memory allocated by this function, use the function MailFree.


MailOpenNotifyEx

This function, an extension of MailOpenNotify, attempts to open a mail database, specify a window handle to receive DB_CEIOD messages, and distinguish between different versions of the message store.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL MailOpenNotifyEx (HANDLE * phMail, WORD* pwVersion
BOOL fAllowCreate, HWND hwndNotify);

Parameters

phMail
[out] Pointer to the mail handle. This handle is set even if the function fails. Upon failure, call the function MailError against the returned handle to obtain the specific error message.
pwVersion
[out] Pointer to the message store version number. If set to NULL, this function does not return anything in this parameter. Otherwise, this function returns 0x0300 on an H/PC Pro and 0x0200 on an H/PC.
fAllowCreate
[in] Boolean for creating a new database. If set to TRUE, this function creates a new mail database when a mail database does not currently exist. If set to FALSE, this function fails when it cannot open or find the mail database.
hwndNotify
[in] Handle to the window to receive DB_CEOID_* notifications. These notifications represent changes made to the database by other handles.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

A desktop computer can use the pwVersion parameter to determine whether it is connected to an H/PC or an H/PC Pro.


MailPutEx

This function, an extension of MailPut, creates a new mail entry in the message store and operates in a multiple hierarchy folder environment.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL MailPutEx (HANDLE hMail, MailMsg*pmm, FID fid);

Parameters

hMail
[in] Handle to the mail context. This handle is created by the MailOpen function.
pmm
[in] Pointer to the MailMsg structure that contains the information for the new entry. This function ignores the dwMsgID member of MailMsg.
fid
[in] Folder identifier of the folder to create the new message in.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function MailError or MailErrorMsg.

Remarks

If this function succeeds, this function sets the oid member of MailMsg with a unique identification number for this mail entry. Other mail functions can use the oid to reference this entry.

This function adds new entries to the message store. To change existing entries, use the MailUpdateEx function.

This function only accepts a MailMsg structure if the pwcHeader and hHeap members are properly initialized with a call to the function MailSetField. The hHeap member must be a handle to a heap you created.

See Also

MailGetEx


MailPutFolderEx

This function, an extension of MailPutFolder, adds, deletes, or renames a folder, and operates in a multiple hierarchy folder environment.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL MailPutFolder (HANDLE hMail, FID fidParent, FID fidFolder,
LPWSTR szName);

Parameters

hMail
[in] Handle to the mail context. This handle is created by the MailOpen function.
fidParent
[in] Folder identifier of the parent mail folder. If no parent folder exists, set fidParent to MAIL_FOLDER_NONE. A folder with created with fidParent set to MAIL_FOLDER_NONE is considered the base folder in a folder hierarchy. This function ignores this parameter if szName is set to NULL.
fidFolder
[in] Folder identifier of the target mail folder. Because a system folder cannot be modified or deleted, fidFolder cannot be any of the following identifiers: MAIL_FOLDER_INBOX, MAIL_FOLDER_OUTBOX, or MAIL_FOLDER_SENT.
szName
[in] Null-terminated string that contains the name of the mail folder. If NULL, this function deletes the folder identified by fidFolder.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function MailError or MailErrorMsg.

Remarks

If the fidFolder parameter identifies a folder that already exists in the message store, this function renames the folder based on the name specified in szName. If the folder exists and szName is NULL, the folder is deleted. If the identifier in fidFolder is not found in the database, this function creates a folder based on the name specified by szName.

To find an unused folder identifier for fidFolder

  1. Start an iterative call on the function MailGetFolderNameEx, with the fID parameter set to MAIL_FOLDER_FIRST or MAIL_FOLDER_FIRST_OTHER.
  2. Continue to call MailGetFolderNameEx until you receive a folder identifier with no accompanying name.

The default mail folder hierarchy for the H/PC Pro is known as ActiveSync. Because all folders within the ActiveSync hierarchy have folder identifiers between 0 and 255, ActiveSync is backward-compatible with earlier versions of Windows CE. All folders outside the ActiveSync hierarchy have folder identifiers of 256 or greater.

See Also

MailGetFolderId


MailUpdateEx

This function, an extension of MailUpdate, replaces an entry in the message store with updated information and operates in a multiple folder hierarchy environment.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL MailUpdateEx (HANDLE hMail, MailMsg* pmm, FID fid,
FID fidTarget, BOOL fDoAll);

Parameters

hMail
[in] Handle to the mail context. This handle is created by the MailOpen function.
pmm
[in] Pointer to the MailMsg structure that contains the mail entry with the updated information.
fid
[in] Folder identifier of the folder this function places the message in. Set fid to MAIL_FOLDER_NONE to keep the message in its current folder.
pfidTarget
[in] Pointer to the target folder identifier of a Copy or Move command. This parameter is only valid if the MAIL_STATUS_MOVE or MAIL_STATUS_COPY flags are set in the dwFlags member of MailMsg. Set pfidTarget to MAIL_FOLDER_NONE if you do not want this function to update the message that is being copied or moved.
fDoAll
[in] Boolean that is set to TRUE if this function updates all members of MailMsg, or to FALSE if this function updates only the dwFlags and wBodyLen members in MailMsg pointed to by pmm. Setting fDoAll to FALSE also updates the fid and pfidTarget parameters, if those parameters are not set to MAIL_FOLDER_NONE.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function MailError or MailErrorMsg.

Remarks

This function changes the entry identified by the oid member of MailMsg. If the entry does not exist in the database, this function fails.

Treat any message that has the MAIL_STATUS_MOVE or MAIL_STATUS_COPY flag set as being located in the pfidTarget folder. This folder may differ from that indicated by fid because a client can attempt to move or copy a message from one folder to another while the client is not connected to a mail server. If this happens, the OS sets the MAIL_STATUS_MOVE or MAIL_STATUS_COPY flag in MailMsg. This function saves the target folder, along with MailMsg, in the store. When the device connects to the mail server, the Inbox client performs the move or copy on the server, then uses this function to clear the existing flag from MailMsg and to set the value of fid to the new target folder.

See Also

MailPut


H/PC Pro Transport API

This section is a reference for the H/PC Pro Transport API. It includes reference entries for all the transport functions supported on Windows CE.


TransportCancel

This function cancels the current transport operation.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportCancel( HANDLE hService);

Parameters

hService
[in] Handle to a private SERVICE structure.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

See Also

TransportDisconnect


TransportCheckForNewMail

This function searches a mail server for new mail.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportCheckForNewMail( HANDLE hService,
CHECKFORNEWMAILCALLBACK pfnCheckNewMailCallback);

Parameters

hService
[in] Handle to a private SERVICE structure.
pfnCheckNewMailCallback
[in] Pointer to a callback function of the following prototype:

BOOL _cdecl CheckNewMailCallback (lpTransportCheckForNewMailInfo *pInfo)

Return Values

TRUE indicates the function has successfully initiated the callback function on the server. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

When checking for new mail, call the function CheckNewMailCallback twice. First, use the callback function to obtain the list of folders to search for new messages. Signal this by setting the fFree parameter of the pInfo structure to FALSE. After checking for new messages, signal the callback function to release the storage used by the TransportFolderList structure by setting fFree to TRUE. When releasing storage, ignore szFriendlyName members in the TransportFolderInfo structures in TransportFolderList.


TransportCopy

This function copies a message to a folder on a mail server.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportCopy(HANDLE hService, MailMsg *MsgPtr,
LPWSTR szDestFolderID);

Parameters

hService
[in] Handle to a private SERVICE structure.
MsgPtr
[in] Pointer to the MailMsg structure. The szSvcID member of MailMsg specifies the service identifier of the message to be copied.
szDestFolderID
[in] Null-terminated string that contains the identifier of the destination folder.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

See Also

TransportDel


TransportCountEx

This function, an extension of TransportCount, determines the number of messages in the mailbox or any other message folder, and returns this count in the lpNumMsgs parameter.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportCountEx(HANDLE hService, LPWSTR szFolderID,
WORD *pwNumMsg);

Parameters

hService
[in] Handle to a private SERVICE structure.
szFolderID
[in] Null-terminated string that contains the identifier of the folder to search.
pwNumMsg
[in] Pointer to the number of messages in the folder specified by szFolderID.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.


TransportDelFolder

This function deletes a folder on a mail server, along with all of the folder’s subfolders and messages.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportDelFolder(HANDLE hService, LPWSTR szFolderID);

Parameters

hService
[in] Handle to a private SERVICE structure.
szFolderID
[in] Null-terminated string that contains the identifier of the folder to delete.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

See Also

TransportDel


TransportDownloadAttachment

This function downloads a specified e-mail attachment.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

Int TransportDownloadAttachment (HANDLE serviceHandle_p,
MailMsg* mailMessage_p, MailAtt* mailAtt_p)

Parameters

serviceHandle_p
[in] Pointer to a handle to a private SERVICE structure.
mailMessage_p
[in] Pointer to a MailMsg structure that contains information regarding the mail message that has the attached message.
mailApp_p
[in/out] Pointer to a MailApp structure that contains information regarding the attached file. The mailApp_p parameter should contain the index of the attachment specified by uiAttachmentNumber, the handle to a valid heap specified by hHeap , and the service identifier of the mail message specified by szSvcId. This function fills in and returns the rest of mailApp_p.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

When implementing this function, save the attached file in the \Temp directory on the Windows CE platform.


TransportDuplicateHandle

This function creates a duplicate of the specified service handle.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportDuplicateHandle(HANDLE hService,
HANDLE *phDuplicate);

Parameters

hService
[in] Handle to a private SERVICE structure.
phDuplicate
[in/out] Pointer to a handle to a private SERVICE structure. This function returns a copy of hService in this parameter.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

Both the original handle and the duplicate handle behave the same. You can use either handle in calls to transport API functions from multiple threads. These calls do not create race conditions on data associated with the service handle.

If a transport service provider does not implement this function, your application cannot perform any multithreading techniques that require two or more handles to the service.


TransportErrorEx

This function returns a transport-defined error code for the last mail error that occurred, as well as a Boolean value that indicates if the error is critical. It is an extension of TransportError.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

int TransportErrorEx(HANDLE, hService, BOOL *pfCritical);

Parameters

hService
[in] Handle to a private SERVICE structure.
pfCritical
[in] Pointer to a Boolean. If set to TRUE, the error is critical. If set to FALSE, the error is not critical.

Return Values

The return values for this function depend on the implementation of this function by the transport.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

An error is critical if further attempts to perform the operation that caused the error are likely to fail as well. For example, “Connection to the server lost,” “Incorrect server name provided,” and “Could not authenticate the user” are all critical errors. Noncritical errors include “Message not found,” “Message flags could not be set,” and “Folder has been deleted.”

If a transport service provider does not implement this function, the Inbox application assumes all errors are critical.


TransportExpunge

This function expunges deleted messages out of specified folders on a mail server.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportExpunge( HANDLE hService, lpTransportFolderList pFolders);

Parameters

hService
[in] Handle to a private SERVICE structure.
pFolders
[in] Pointer to a TransportFolderList structure. This structure contains the list of folders to expunge messages from.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

TransportFolderList stores an array of TransportFolderInfo structures. This function uses the members of the TransportFolderInfo structures in the following ways:

  • Ignores szFriendlyName and fidStoreID
  • Uses szServiceId to uniquely identify folders

See Also

TransportDel,TransportFreeMsg


TransportFreeFolderID

This function frees storage allocated by TransportGetFolderId or TransportPutFolder.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportFreeFolderID(HANDLE hService, LPWSTR szFolderID);

Parameters

hService
[in] Handle to a private SERVICE structure.
szFolderID
[in] Null-terminated string that contains the identifier of a folder for which storage was allocated by the function TransportGetFolderId or TransportPutFolder.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.


TransportFreeFolderList

This function frees the storage allocated by TransportGetFolders.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportFreeFolderList(HANDLE hService,
lpTransportFolderList pFolders);

Parameters

hService
[in] Handle to a private SERVICE structure.
pFolders
[in] Pointer to the TransportFolderList structure to be freed.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.


TransportGetFolders

This function returns a list of folders from a transport mail server.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportGetFolders(HANDLE hService, LPWSTR szParentID,
lpTransportFolderList *ppFolders);

Parameters

hService
[in] Handle to a private SERVICE structure.
szParentID
[in] Null-terminated string that contains the identifier of the parent folder. If szParentID is NULL, this function returns a list of top-level folders from the mail server.
ppFolders
[out] Pointer to the pointer to a TransportFolderList structure used by TransportGetFolders to return the folder list. TransportFolderList contains a list of TransportFolderInfo structures.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

This function only returns the first level of subfolders directly beneath the parent folder.

This functiononly sets the szFriendlyName and szServiceID members of the TransportFolderInfo structures in TransportFolderList, and ignores the fidStoreID member.


TransportGetInboxId

This function return the service identifier of the Inbox folder on a mail server.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportGetInboxID(HANDLE hService, LPWSTR *pszInboxID);

Parameters

hService
[in] Handle to a private SERVICE structure.
pszInboxID
[out] Pointer to a null-terminated string. This function returns the identifier of the Inbox folder in this parameter.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

The client is responsible for calling TransportFreeFolderId to free storage allocated on the server by this function.


TransportMove

This function moves a message to a folder on a mail server.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportMove(HANDLE hService, MailMsg *MsgPtr,
LPWSTR szDestFolderID);

Parameters

hService
[in] Handle to a private SERVICE structure.
MsgPtr
[in] Pointer to a MailMsg structure. The szSvcID member of MailMsg specifies the service identifier of the message to be moved.
szDestFolderID
[in] Null-terminated string that contains the identifier of the destination folder.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

See Also

TransportDel


TransportPut

This function adds a message to a folder on a server.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportPut(HANDLE hService, LPWSTR szFolderID,
MailMsg *MsgPtr);

Parameters

hService
[in] Handle to a private SERVICE structure.
szFolderID
[in] Null-terminated string that contains the identifier of the folder to add the message to.
MsgPtr
[in] Pointer to a MailMsg structure. The szSvcID member of MailMsg specifies the service identifier of the message to be placed on the server.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

The transport DLL is responsible for initializing the szSvcId and szSvcNam members of MailMsg. The transport DLL is also responsible for copying attachments and non-Interpersonal Message (non-IPM) properties. These properties are listed in the oid member of MailMsg.


TransportPutFolder

This function creates a subfolder within a specified parent folder on a mail server.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportPutFolder(HANDLE hService, LPWSTR szFolderName,
LPWSTR szParentID, LPWST*pszCreatedID);

Parameters

hService
[in] Handle to a private SERVICE structure.
szFolderName
[in] Null-terminated string that contains the name of the folder to be created.
szParentID
[in] Null-terminated string that contains the identifier of the parent folder. If szParentID is NULL, this function creates the new folder in the root mail directory.
pszCreatedID
[in] Pointer—initialized by this function—to the null-terminated string that contains the identifier of the created folder.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

The client is responsible for calling the function TransportFreeFolderId to free storage allocated by this function.


TransportRecvEx

This function, an extension of TransportRecv, receives messages from not only the mail server, but also any specified folder on the mail server as well.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportRecvEx(HANDLE hService, LPWSTR szFolderID,
WORD wMsgID, short sNumLines, MailMsg *MsgPtr,
lpMailAttArray *lplMaa);

Parameters

hService
[in] Handle to a private SERVICE structure.
szFolderID
[in] Null-terminated string that contains the identifier of the folder in which the message originates.
wMsgID
[in] Specifies the identifier of the message for this session. It is either 0 or in the range from 1 to the number of messages returned by the function TransportCountEx. If wMsgID is 0, this function uses the szSvcId member of the MailMsg structure pointed to by MsgPtr instead.
sNumLines
[in] Specifies the number of lines of the message to receive. This function fills MailMsg with the message header values, the number of lines from the message body as specified in sNumLines, and any attachment header values. It can also be one of the following values:
TRANSPORT_MSG_EXIST
Checks for the message described in wMsgID. If this message exists, this function returns the message service identifier in the scSvcId member of MailMsg.
TRANSPORT_HEADERS
Parses the message header and places the information in MsgPtr, and returns attachment header information in the lplpMaa parameter.
TRANSPORT_ALL_LINES
Returns the full message, including headers and body text, in MailMsg, as well as all attachments through lplpMaa, subject to the user’s preference. If the user has turned off the download attachment option, this function returns only the attachment header information.
MsgPtr
[in/out] Pointer to a MailMsg structure that receives the message information. The szSvcID member of MailMsg specifies the service identifier of the message to be received.
lplpMaa
[in] Long pointer to the long pointer to a MailAttArray structure, which contains any attachments the message may have.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.


TransportSetMsgFlags

This function sets mail message flags in a message on the mail server.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportSetMsgFlags(HANDLE hService, MailMsg *MsgPtr, DWORD dwFlags, BOOL fValue);

Parameters

hService
[in] Handle to a private SERVICE structure.
MsgPtr
[in] Pointer to a MailMsg structure. The szSvcID member of MailMsg specifies the service identifier of the message whose flags are to be modified.
dwFlags
[in] Specifies a bitmask for the flags in MailMsg pointed to by MsgPtr.
fValue
[in] Boolean value to set the flags to.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.

See Also

TransportProps


TransportUIDsChanged

This function determines whether or not a server has changed all the service identifiers since the last connection.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL TransportUIDsChanged(HANDLE hService, BOOL *pfChanged);

Parameters

hService
[in] Handle to a private SERVICE structure.
pfChanged
[out] Pointer a Boolean that indicates the result of the query. If set to TRUE, the server has changed all the service identifiers since the last connection. If set to FALSE, the server has not changed all the service identifiers.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

The transport service provider must implement this function in a DLL registered as a mail service. The Inbox application can then load this DLL and call this function.


TNEF APIs

This section is a reference for the H/PC Transport-Neutral Encapsulation Format (TNEF) APIs. It includes reference entries for all the TNEF functions supported on Windows CE.


ModifiedUTF7ToUnicode

This function converts a modified UTF7 string into Unicode.

At a Glance

Header file: | Tnefapi.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

int WINAPI ModifiedUTF7ToUnicode (LPCSTR lpMultiByteSr,
int ccMultiByte, LPWSTR lpWideCharStr, int ccWideChar);

Parameters

lpMultibyteStr
[in] Long pointer to the address of the string to convert.
ccMultiByte
[in] Integer that contains the number of bytes in the string pointed to by lpMultibyteStr.
lpWideCharStr
[out] Long pointer to the address of a wide-character buffer. This buffer returns the converted character string.
ccWideChar
[in] Integer that contains the size of the output buffer pointed to by lpWideCharStr.

Return Values

The character count of the Unicode string, including the terminating null character, indicates success. Zero indicates failure.

See Also

TnefConvertToUnicode, UnicodeToModifiedUTF7


TnefBuildInfo

This function creates an encoded Transport-neutral Encapsulation Format (TNEF) file.

At a Glance

Header file: | Tnefapi.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI TnefBuildInfo(const TNEFINFO * pti, LPWSTR szSubject,
MailNonIpmInfo * lpnii, MailAttArray * lpmaa);

Parameters

pti
[in] Pointer to a TNEFINFO structure that describes the file to create.
szSubject
[in] Null-terminated string that contains the message subject for the file.
lpnii
[in] Long pointer to a MailNonIpmInfo structure that contains the non-Interpersonal Message (non-IPM) properties for the file.
lpmaa
[in] Long pointer to a MailAttArray) structure that contains file attachments for the file. Because Windows CE version 2.10 does not currently support bundling attachments to TNEF files, set this parameter to NULL.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

If successful, this function assigns a newly-created file the name stored in the szTnefFileName member of TNEFINFO.

If necessary, use the UUEncode format for encoding your attachments. You can also use MIME sections if your application supports the MIME format.

Currently, this function supports only meeting request properties.

See Also

TnefDecodeFile


TnefConvertToUnicode

This function converts a string encoded with a specific code page to Unicode.

At a Glance

Header file: | Tnefapi.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

INT WINAPI TnefConvertToUnicode (UINT CodePage, DWORD dwFlags,
LPCSTR lpMultiByteStr, int cchMultiByte, LPWSTR lpWideCharStr,
int cchWideChar);

Parameters

CodePage
[in] Unsigned integer that contains the number of the code page to decode from. The following table shows supported code pages.
Code page
Name
Contains
1250 | Windows 1250 | Central European languages
1251 | Windows 1251 | Cyrillic
1252 | Windows 1252 | Western European languages
1253 | Windows 1253 | Greek
1254 | Windows 1254 | Turkish
1255 | Windows 1255 | Hebrew
1256 | Windows 1256 | Arabic
1257 | Windows 1257 | Baltic languages
1258 | Windows 1258 | Vietnamese
20866 | KOI8-R | Russian Cyrillic standard
21886 | KOI8-U | Ukrainian Cyrillic standard
28592 | ISO 8859-2 | Central European languages
28593 | ISO 8859-3 | Esperanto/Galician/Maltese/ incomplete Turkish
28594 | ISO 8859-4 | Baltic languages
28595 | ISO 8859-5 | Cyrillic
28596 | ISO 8859-6 | Arabic
28597 | ISO 8859-7 | Greek
28598 | ISO 8859-8 | Hebrew
28599 | ISO 8859-9 | Turkish
28600 | ISO 8859-10 | Nordic languages, except Skolt Sami
28604 | ISO 8859-14 | Celtic
28605 | ISO 8859-15 | Western Europe, updated
65000 | UTF-7 | 7-bit Unicode encoding
65001 | UTF-8 | 8-bit Unicode encoding

dwFlags
[in] Specifies a bitmask of flags that indicate whether to translate to precomposed or composite wide characters if a composite form exists, whether to use glyph characters in place of control characters, and how to deal with invalid characters. It can be combination of the following flag constants:
MB_PRECOMPOSED
Always use precomposed characters—that is, characters in which a base character and a nonspacing character have a single character value. If an H/PC Pro does not recognize the value in CodePage, it defaults to MB_PRECOMPOSED. This flag cannot be used with MB_COMPOSITE.
MB_COMPOSITE
Always use composite characters—that is, characters in which a base character and a nonspacing character have different character values. This flag cannot be used with MB_PRECOMPOSED.
MB_ERR_INVALID_CHARS
If the function encounters an invalid input character, it fails and GetLastError returns ERROR_NO_UNICODE_TRANSLATION.
MB_USEGLYPHCHARS
Use glyph characters instead of control characters

The function’s default behavior is to translate to the precomposed form. If a precomposed form does not exist, the function attempts to translate to a composite form.

The flags MB_PRECOMPOSED and MB_COMPOSITE are mutually exclusive. The MB_USEGLYPHCHARS flag and the MB_ERR_INVALID_CHARS can be set regardless of the state of the other flags.

lpMultiByteStr
[in] Long pointer to the input string.
ccMultiByte
[in] Character count of the input string.
lpWideCharStr
[in] Long pointer to the output buffer.
cchWideChar
[in] Integer that returns the character count of the output buffer

Return Values

The number of characters copied to the output buffer indicates success. If the output buffer size is 0, the function returns the size of the buffer required to contain the output string. Zero indicates failure.

See Also

ModifiedUTF7ToUnicode, UnicodeToModifiedUTF7


TnefDecodeBuffer

This function decodes a buffer from a specified format into ASCII.

At a Glance

Header file: | Tnefapi.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI TnefDecodeBuffer(INETENCODE EncodeType,
LPSTR BufToDecode, BYTE * DecodedBuf, UINT * puiLength);

Parameters

EncodeType
[in] INETENCODE enumeration value that describes one of the following the encoding formats:
Base64
Quoted-Printable
UUEncode

BufToDecode
[in] Input buffer to decode.
DecodedBuf
[in] Pointer to the decoded buffer.
puiLength
[in/out] Pointer to an unsigned integer that contains the size of the output buffer in bytes. Returns the size of the decoded data in bytes.

Return Values

TRUE indicates success. FALSE indicates failure. To get extended error information, call the function TransportError or TransportErrorMsg.

Remarks

This function fails if the output buffer is not large enough to contain all the decoded data. When this happens, puiLength returns the size of the buffer necessary to contain the decoded data.

See Also

TnefEncodeBuffer


TnefDecodeFile

This function decodes a file into a specified format.

At a Glance

Header file: | Tnefapi.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI TnefDecodeFile(INETENCODE EncodeType,
LPWSTR FileToDecode, LPWSTR DecodedFileName);

Parameters

EncodeType
[in] INETENCODE enumeration value that describes one of the following the encoding formats:
Base64
Quoted-Printable
UUEncode

FiletoDecode
[in] Pointer to the name of the file to decode.
DecodedFileName
[in] Pointer to the name of the output file.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

If successful, this function outputs the file specified by DecodedFileName. Delete this file once you are finished with it.

See Also

TnefEncodeFile


TnefEncodeBuffer

This function encodes a buffer into a specified format.

At a Glance

Header file: | Tnefapi.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI TnefEncodeBuffer(INETENCODE EncodeType, UINT cbIn,
BYTE * BufToEncode, UINT * pcbOut, LPSTR EncodedBuf);

Parameters

EncodeType
[in] INETENCODE enumeration value that describes one of the following the encoding formats:
Base64
Quoted-Printable
UUEncode

cbIn
[in] Unsigned integer that contains the size of the input buffer, in bytes.
BufToEncode
[in] Pointer to a buffer that contains the data to encode.
pcbOut
[in/out] Pointer to an unsigned integer that contains the size of the output buffer. Returns the size of the encoded data.
EncodedBuf
[in/out] Pointer to the output buffer.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

This function fails if the output buffer is not large enough to contain all the encoded data.

See Also

TnefDecodeBuffer


TnefEncodeFile

This function encodes a file into a specified format..

At a Glance

Header file: | Tnefapi.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

LPWSTR WINAPI TnefEncodeFile(LPWSTR FileToEncode,
INETENCODE EncodeType);

Parameters

FileToEncode
[in] Pointer to a character string that contains the name of the file to encode.
EncodeType
[in] INETENCODE enumeration value that describes one of the following the encoding formats:
Base64
Quoted-Printable
UUEncode

Return Values

The file name of the encoded file indicates success. NULL indicates failure.

Remarks

This function does not alter the file described in FileToEncode.

You are responsible for deleting the file created by this function and for calling LocalFree on the name returned by TnefEncodeFile.

See Also

TnefDecodeFile


TnefGetInfo

This function extracts information from an encoded transport-neutral encapsulation format (TNEF)file.

At a Glance

Header file: | Tnefapi.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

BOOL WINAPI TnefGetInfo(const TNEFINFO * pti,
MailNonIpmInfo ** lplpnii, MailAttArray ** lplpmaa);

Parameters

pti
[in] Pointer to a TNEFINFO structure that describes the TNEF file.
lplpnii
[out] Long pointer to a long pointer to a MailNonIpmInfo structure that returns the non-Interpersonal Message (IPM) information of the TNEF file.
lplpmaa
[out] Long pointer to a long pointer to a MailAttArray structure that returns the file attachments of the TNEF file. This parameter is optional; you do not have to receive the attachment information.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

Regardless of whether this functions succeeds or fails, this function deletes the file described by the structure that pti points to.

While Windows CE version 2.10 does not support bundling attachments to a TNEF file, this function can extract meeting request properties from a TNEF file.

See Also

TnefBuildInfo


UnicodeToModifiedUTF7

This function converts a Unicode string into a modified UTF7 string.

At a Glance

Header file: | Tnefapi.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

int WINAPI UnicodeToModifiedUTF7 (LPCWSTR wszIn, int cchIn,
LPSTR pchOut, Int cchOut);

Parameters

wszIn
[in] Pointer to the address of the string to convert.
cchIn
[in] Number of characters in the string specified by wszIn.
pchOut
[out] Pointer to the output buffer.
cchOut
[in] Number of characters in the output buffer.

Return Values

The number of Unicode characters translated and stored in pchOut is returned. A number equal to the value of cchIn indicates success. A number less than the value of cchIn indicates failure.

See Also

ModifiedUTF7ToUnicode, TnefConvertToUnicode


H/PC Pro Structures

This section is a reference for H/PC Pro structures. It contains reference entries on the TNEF and transport structures supported on Windows CE.


TNEFINFO

This structure contains Multipurpose Internet Mailing Extension (MIME) information for a Transport-neutral Encapsulation Format (TNEF) file. This structure is also used to store data by a variety of encoding and decoding APIs.

At a Glance

Header file: | Tnefapi.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

typedef struct _tnefinfo{
INETENCODE wContentEncoding;
BOOL fAttHdrs;
HANDLE hHeap
LPWSTR szTnefCorrelator;
WCHAR szTnefFileName[MAX_PATH]
} TNEFINFO;

Members

wContentEncoding
The INETENCODE enumeration that contains the encoding style for the file.
fAttHdrs
Boolean value that contains information for the TnefGetInfo function. If set to TRUE, TnefGetInfo retrieves attachment information from a TNEF file. If set to FALSE, the function retrieves only meeting request information.
hHeap
Handle to the message heap that allocates memory for the file.
szTnefCorrelator
Null-terminated string that contains the TNEF correlator from the message header.
szTnefFileName
Null-terminated string that contains the file name of the TNEF file.

See Also

TnefBuildInfo


TransportCheckForNewMailInfo

This structure is used to pass folder information between the TransportCheckForNewMail function and its callback function.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

typedef struct TransportCheckForNewMailInfo{
TransportFolderList* ptfl;
BOOL fFree;
HANDLE hTerminateEvent;
DWORD dwReserverd;
} TransportCheckForNewMailInfo, *lpTransportCheckForNewMailInfo;

Members

pftl
Pointer to a TransportFolderList structure that contains the names of the folders to check for new mail in.
fFree
Boolean that indicates if ptfl should be allocated or freed. If fFree is set to TRUE, the client creates a TransportFolderList structure and assigns ptfl to the structure. If fFree is set to FALSE, the client frees the TransportFolderList structure pointed to by ptfl.
hTerminateEvent
Handle to the event used to stop the callback function from checking for new mail.
dwReserved
Reserved DWORD; set to 0.


TransportFolderInfo

This structure contains name and identifier information for a folder on a mail server.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

typedef struct TransportFolderInfo_s {
LPWSTR szFriendlyName;
LPWSTR szServiceID;
FID fidStoreID;
} TransportFolderInfo, *lpTransportFolderInfo;

Members

szFriendlyFolderName
Null-terminated string that contains a friendly folder name.
szServiceID
Null-terminated string that contains the service identifier for the folder.
fidStoreID
Folder identifier of the message store.

Remarks

A transport service uses this structure to store information about a specific folder located on a server. The TransportFolderList structure contains an array of TransportFolderInfo structures. These structures describe the folder hierarchy of the mail server.

See Also

TransportCheckForNewMailInfo


TransportFolderList

This structure contains the number, friendly names, and identifiers of a series of folders on a mail server.

At a Glance

Header file: | Msgstor2.h
Platforms: | H/PC Pro
Windows CE versions: | 2.10 and later

Syntax

typedef struct TransportFolderList_s {
UINT uiCount;
lpTransportFolderInfo FolderArray[];
} TransportFolderList, *lpTransportFolderList;

Members

uiCount
Unsigned integer that contains the number of TransportFolderInfo structures in FolderArray.
FolderArray
Array of TransportFolderInfo structures. Each TransportFolderInfo structure contains the friendly name and identifier of a specific folder.

Remarks

The TransportGetFolders function uses TransportFolderList to pass folder information from a server to a client.

See Also

TransportExpunge


Microsoft Pocket Excel File Format

The file format in which Microsoft Pocket Excel workbooks are saved is an abbreviated form of the binary interchange file format (BIFF). For details on the BIFF file format, developers should refer to the Excel Developer’s Kit, available from Microsoft Press. This document details differences between the Desktop BIFF file format and that used by Pocket Excel. From this point forward, “BIFF” refers to the Pocket Excel file format.


Record Types

Some general characteristics of BIFF records:

  • Every BIFF record begins with a single byte that identifies the record. The hexadecimal value of the record number is included in parentheses in the heading of the record description. Following the record byte is the record data that describes the formula, window, etc.
  • Strings in Pocket Excel 1.0 files are always stored in ASCII format, so character counts are equivalent to byte counts. Pocket Excel 2.0, on the other hand, stores all strings in Unicode (two bytes/character), so all character counts are WORD counts.

The following sections detail the different types of records. Those marked with PXL 2.0 or PXL 1.0 only apply to their respective versions.


BLANK: Cell Value, Blank Cell (01h)

A BLANK record describes an empty cell. The rw field contains the zero-based row number. The col field contains the zero-based column number. The record data has the following format:

Record Data

Offset
Name
Size
Contents
0 | rw | 2 | Row
2 | col | 1 | Column
3 | ixfe | 2 | Index to XF record


BOF: Beginning of File (09h)

The BOF record marks the beginning of the workbook in the BIFF file. It also marks the beginning of record groups for sheets in the workbook. The record data has the following format.

Record Data

Offset
Name
Size
Contents
0 | vers | 2 | Version number
2 | dt | 2 | Substream type

Parameters

dt
The dt field specifies the type of the substream. Only worksheets and the workbook globals are supported.

0005h = Workbook Globals

0010h = Worksheet


BOOLERR: Cell Value, Boolean or Error (05h)

A BOOLERR record describes a cell that contains a constant Boolean or error value. The rw field contains the zero-based row number. The col field contains the zero-based column number.

Record Data

Offset
Name
Size
Contents
0 | rw | 2 | Row
2 | col | 1 | Column
3 | ixfe | 2 | Index to XF record
5 | bBoolErr | 1 | Boolean value or error value
6 | fError | 1 | Boolean error flag

Parameters

bBoolErr
Contains the Boolean or error value, as specified by the fError field.
fError
If set to 0 (zero), the bBoolErr field contains a Boolean value. If set to 1 (one), the bBoolErr field contains an error value.


BOUNDSHEET: Sheet Information (85h)

This record stores the sheet name.

Record Data

Offset
Name
Size
Contents
0 | Reserved | 1 | Reserved (must be set to zero).
1 | cch | 1 | Length of sheet name, in characters
2 | rgch | Variable | Sheet name


COLINFO: Column Formatting Information (7Dh) [PXL 1.0]

The COLINFO record describes the column formatting for a column.

Record Data

Offset
Name
Size
Contents
0 | col | 2 | Column
2 | grbit | 2 | Column width, in pixels
4 | ixfe | 2 | Index to the XF record that contains the default format for the column

Parameters

grbit
The grbit field is set up as follows
Bit
Size
Name
Contents
0 | 14 | coldx | Column width, in pixels
14 | 1 | fHidden | Set if the column is hidden
15 | 3 | Unused | Unused by Pocket Excel


COLINFO: Column Formatting Information (7Dh) [PXL 2.0]

The COLINFO record describes the column formatting for a column.

Record Data

Offset
Name
Size
Contents
0 | colfirst | 2 | First Column this applies to
2 | colLast | 2 | Last Column this applies to
4 | coldx | 2 | Column width in 1/255s of a character
6 | ixfe | 2 | Index to format to apply to columns
8 | grbit | 1 | Option flags

Parameters

grbit
The grbit member is structured as follows:
Bit
Size
Name
Contents
0 | 1 | fHidden | Set if the column had been hidden or set to zero width
1 | 1 | fUserSet | Set if the column width has been set by the user (as opposed to AutoFormat)
2 | 3 | iOutLevel | Unused by Pocket Excel
5 | 3 | fCollapsed | Unused by Pocket Excel
8 | 2 | Unused | Unused by Pocket Excel


DEFAULTROWHEIGHT: Default Row Height (25h) [PXL 2.0]

The DEFAULTROWHEIGHT record contains the row height for rows that do not contain any entries.

Record Data

Offset
Name
Size
Contents
0 | grbit | 2 | Flags
2 | miyRw | 2 | Row height, in twips

Parameters

grbit
The grbit field is structuredas follows:
Bit
Size
Name
Contents
0 | 1 | fHidden | Set if row is hidden
1 | 15 | Unused | Unused


DEFCOLWIDTH: Default Column Width (55h) [PXL 2.0]

The DEFCOLWIDTH record contains the default column width.

Record Data

Offset
Name
Size
Contents
0 | grbit | 2 | Flags
2 | coldx | 2 | Column width, in characters
4 | ixfe | 2 | Format index

Parameters

grbit
The grbit parameter is structured as follows:
Bit
Size
Name
Contents
0 | 1 | fHidden | Set if column is hidden
1 | 1 | fUserSet | Set if the column width had been set by the user
2 | 14 | Unused | Unused


EOF: End of File (0Ah)

The EOF record marks the end of the workbook or the end of one of the substreams in the workbook. It has no record data field.


FILEPASS: File Password (2Fh) [PXL 2.0]

Contains an encrypted password which is used to encrypt the remainder of the file. Third-party tools that encounter this record should just stop reading the file.


FONT: Font Description (31h)

Contains information about the font.

Record Data

Offset
Name
Size
Contents
0 | dwHeight | 2 | Height of font, in twips
2 | grbit | 2 | Font attributes
4 | Reserved | 2 | Reserved
6 | bls | 2 | Bold style
8 | Reserved | 2 | Reserved
10 | uls | 1 | Underline style
11 | bFamily | 1 | Font Family
12 | bCharSet | 1 | Character set
13 | Reserved | 1 | Reserved
14 | cch | 1 | Length of font name, in characters
15 | rgch | Variable | Font Name

Parameters

grbit
The grbit field contains the following font attributes:
Bit
Mask
Name
Contents
1 02h fItalic 1, if font is italic, 0 if not

uls
The underline style

00h = None

01h = Single


FORMAT: Number Format (1Eh)

The FORMAT record describes a number format in the workbook.

Record Data

Offset
Name
Size
Contents
0 | cce | 1 | Length of format string, in characters
1 | rgch | Variable | Number format string


FORMULA: Cell Formula (06h)

A FORMULA record describes a cell that contains a formula.

Record Data

Offset
Name
Size
Contents
0 | rw | 2 | Row
2 | col | 1 | Column
3 | ixfe | 2 | Index to XF record
5 | num | 8 | Current value of formula
13 | grbit | 1 | Option flags
14 | cce | 2 | Length of parsed expression, in bytes
16 | rgce | Variable | Parsed expression

Parameters

grbit
The grbit field contains the following option flags.
Bits
Mask
Name
Contents
0 | 01h | fAlwaysCalc | Always calculate the formula
2 | 04h | fCirc | Formula is part of a circular reference

rw
The rw field contains the zero-based row number.
col
The col field contains the zero-based column number.
num
If the formula evaluates to a number, the num field contains the current calculated value of the formula in 8-byte IEEE format. If the formula evaluates to a string, a Boolean, or an error value, the most-significant 2 bytes of the num field are FFFFh.

A Boolean value is stored in the num field as shown in the following table.
Offset
Name
Size
Contents
0 | otBool | 1 | =1, always
1 | Reserved | 1 | Must be zero
2 | f | 1 | Boolean value
3 | Reserved | 3 | Must be zero
6 | fExpr0 | 2 | = FFFFh, always

An error value is stored in the num field as shown in the following table.
Offset
Name
Size
Contents
0 | otErr | 1 | = 2, always
1 | Reserved | 1 | Must be zero
2 | err | 1 | Error value
3 | Reserved | 3 | Must be zero
6 | fExpr0 | 2 | = FFFFh, always

If the formula evaluates to a string, the num field has the structure shown in the following table. The string value is not stored in the num field; instead, it is stored in a STRING record that immediately follows the FORMULA record.
Offset
Name
Size
Contents
0 | otString | 1 | = 0, always
1 | Reserved | 5 | Must be zero
6 | fExpr0 | 2 | = FFFFh, always

For Pocket Excel 2.0, if the formula evaluates to a blank string, the num field has the following structure No STRING record is generated in this case.
Offset
Name
Size
Contents
0 | otBlankString | 1 | = 3, always
1 | Reserved | 5 | Must be zero
6 | fExpr0 | 2 | = FFFFH

rgce
The rgce field contains the formula in its parsed format.


LABEL: Cell Value, String Constant (04h)

A LABEL record describes a cell that contains a string constant.

Record Data

Offset
Name
Size
Contents
0 | rw | 2 | Row
2 | col | 1 | Column
3 | ixfe | 2 | Index to XF record
5 | cch | 2 | Length of the string, in characters
7 | rgch | Variable | The string

Parameters

rw
The zero-based row number
col
The zero-based column number
cch
String length. Must be between 0000h and 00FFh (0-255)


NAME: Defined Name (18h) [PXL 1.0]

The NAME record describes a defined name in the workbook.

Record Data

Offset
Name
Size
Contents
0 | cch | 1 | Length of the name text, in characters
1 | cce | 2 | Length of the name definition, in bytes
3 | ixals | 2 | Index to sheet that contains name
5 | rgch | Variable | Name text
Variable | rgce | Variable | Name definition

Parameters

cch
The cch field contains the length of the name text.
rgch
The rgch field contains the text itself.
cce
The cce field contains the length of the name definition.
rgce
The rgce field contains the definition itself. The location of the rgce within the record depends on the length of the name text (rgch) field. The name definition (rgce) is stored in the Microsoft Pocket Excel parsed format.
ixals
The NAME record stores two types of names: global names and local names. A global name is defined for an entire workbook, and a local name is defined on a single sheet. For example, MyName is a global name, while Sheet1!MyName is a local name. The ixals field in the NAME record will be nonzero for local names.


NAME: Defined Name (18h) [PXL 2.0]

The NAME record describes a defined name in the workbook.

Record Data

Offset
Name
Size
Contents
0 | grbit | 2 | Option flags
2 | cch | 1 | Length of the name text, in characters
3 | cce | 2 | Length of the name definition, in bytes
5 | ixals | 2 | Index to sheet that contains name
7 | rgch | Variable | Name text
Variable | rgce | Variable | Name definition

Parameters

grbit
grbit fields are as follows:
Bit
Size
Name
Contents
0 | 1 | fHidden | Set if name is hidden
1 | 15 | Unused | Unused. Must be zero

cch

The cch field contains the length of the name text.

rgch
The rgch field contains the text itself.
cce
The cce field contains the length of the name definition.
rgce
The rgce field contains the definition itself. The location of the rgce within the record depends on the length of the name text (rgch) field. The name definition (rgce) is stored in the Microsoft Pocket Excel parsed format.
ixals
The NAME record stores two types of names: global names and local names. A global name is defined for an entire workbook, and a local name is defined on a single sheet. For example, MyName is a global name, while Sheet1!MyName is a local name. The ixals field in the NAME record will be nonzero for local names.


NUMBER: Cell Value, Floating-Point Number (03h)

A NUMBER record describes a cell containing a constant floating-point number. The rw field contains the zero-based row number. The col field contains the zero-based column number. The number is contained in the num field in 8-byte IEEE floating-point format.

Record Data

Offset
Name
Size
Contents
0 | rw | 2 | Row
2 | col | 1 | Column
3 | ixfe | 2 | Index to XF record
5 | num | 8 | Floating point value

Parameters

rw
A zero-based row number
col
A zero-based column number
num
A floating-point number in 8-byte IEEE floating-point format.


PANE: Number of Panes and their Position (41h) [PXL 2.0]

The PANE record describes the number and position of unfrozen panes in a window.

Record Data

Offset
Name
Size
Contents
0 | x | 2 | Horizontal position
2 | y | 2 | Vertical position
4 | rwTop | 2 | Top row visible
6 | colLeft | 2 | Leftmost column visible
8 | pnnAct | 1 | Pane number

Parameters

x
Horizontal position of the split. Zero if there is no split. The value is given in pixels when panes are not frozen, and in rows/columns when they are.
y
Vertical position of the split. Zero if there is no split. The value is given in pixels when panes are not frozen, and in rows/columns when they are.
rwTop
Top row visible in the lower pane
colLeft
Leftmost column visible in the right pane
pnnAct
Pane number of the active pane. Values for pnnAct are:

0 = bottom right

1 = top right

2 = bottom left

3 = top left


ROW: Describes a Row (08h)

This record type describes a row.

Record Data

Offset
Name
Size
Contents
0 | rw | 2 | Row number
2 | miyRw | 2 | Row height
4 | grbit | 2 | Option flags
6 | ixfe | 2 | Index to the XF record for the row

Parameters

rw
The rw field contains the zero-based row number.
miyRw
In a Pocket Excel 1.0 file, the miyRw field contains the row height in pixels. In Pocket Excel 2.0, miyRw contains the row height in twips.

If you hide the row, either by setting the row height to zero or by choosing the Hide command, miyRw still contains the original row height. This allows Microsoft Pocket Excel to restore the original row height.

grbit
The grbit field contains the following option flags.
Bit
Mask
Name
Contents
0 | 01h | fHidden | = 1 if contents are hidden
1 | 02h | fUserSet | = 1 if row’s height has been manually set [PXL 2.0 only


SELECTION: Current Selection (1Dh)

The SELECTION record stores the selection.

Record Data

Offset
Name
Size
Contents
0 | rwTop | 2 | Top Row of the selection
2 | colLeft | 1 | Leftmost column of the selection
3 | rwBottom | 2 | Bottom row of the selection
5 | colRight | 1 | Rightmost column of the selection
6 | rwActive | 2 | Row number of the active cell
8 | colActive | 1 | Column number of the active column


STRING: String Value of a Formula (07h)

The STRING formula contains the value of a formula that evaluates to a string. The STRING record for a formula is always immediately after the FORMULA record whose value it contains.

Record Data

Offset
Name
Size
Contents
0 | cch | 1 | Length of the string, in characters
1 | rgch | Variable | String


WINDOW1: Window Information (3Dh) [PXL 2.0]

The WINDOW1 information contains workbook-level window attributes.

Record Data

Offset
Name
Size
Contents
0 | grbit | 2 | Option flags. Must be set to zero
2 | itabCur | 2 | Index of selected workbook tab (active sheet)


WINDOW2: Sheet Window Information (3Eh) [PXL 1.0]

The WINDOW2 record contains window attributes for a sheet in the workbook.

Record Data

Offset
Name
Size
Contents
0 | rwTop | 2 | Top row visible in the window
2 | colLeft | 1 | Leftmost column visible in the window


WINDOW2: Sheet Window Information (3Eh) [PXL 2.0]

The WINDOW2 record contains window attributes for a sheet in the workbook.

Record Data

Offset
Name
Size
Contents
0 | rwTop | 2 | Top row visible in the window
2 | colLeft | 1 | Leftmost column visible in the window
4 | grbit | 2 | Option flags

Parameters

grbit
The grbit parameter contains the following information, packed into two bytes:
Bit
Size
Name
Contents
0 | 3 | fUnused | Unused
3 | 1 | fFrozen | Set if panes are frozen
4 | 4 | fUnused | Unused
8 | 1 | fFrozenNoSplit | Set if panes are frozen with no split
9 | 7 | fUnused | Unused

fFrozen
Set if panes are frozen. The split positions in the PANE record will be column indices rather than pixels.


XF: Extended Format (E0h) [PXL 1.0]

A BIFF file can contain as many XF records as necessary to describe the different cell formats in a workbook. The XF record stores formatting properties for cells. The ixfe of a cell record (BLANK, LABEL, NUMBER, and so on) points to a cell XF record.

Record Data

Offset
Name
Size
Contents
0 | ixfnt | 2 | Index to FONT record
2 | ixfmtParent | 2 | Unused
4 | ixnf | 2 | Index to FORMAT record plus 230
6 | fAttributes | 4 | Unused
10 | fBaseAttr | 2 | Base attribute flags
12 | fTextAttr | 2 | Text attribute flags
14 | icvFore | 2 | Foreground color
16 | icvFill | 2 | Unused
18 | icvBorder | 2 | Unused
20 | backstyle | 1 | Unused
21 | borderstyle | 1 | Unused


XF: Extended Format (E0h) [PXL 2.0]

A BIFF file can contain as many XF records as necessary to describe the different cell formats in a workbook. The XF record stores formatting properties for cells. The ixfe of a cell record (BLANK, LABEL, NUMBER, and so on) points to a cell XF record.

Record Data

Offset
Name
Size
Contents
0 | ixfnt | 2 | Index to FONT record
4 | ixnf | 2 | Index to FORMAT record plus 230
6 | fattributes | 4 | Unused, set to 0xFFFF
10 | fBaseAttr | 2 | Base attribute flags
12 | fTextAttr | 2 | Text attribute flags
14 | icvFore | 2 | Background color of cell
16 | icvFill | 2 | Unused
18 | bRight | 1 | Right border style
19 | bTop | 1 | Top border style
20 | bLeft | 1 | Left border style
21 | bBottom | 1 | Bottom border style
20 | backstyle | 1 | Unused
21 | borderstyle | 1 | Unused

Parameters

fBaseAttr
The fBaseAttr flags are packed into the first four bits of this parameter:
Bit
Size
Name
Contents
0 | 1 | m_cFixed | Unused
1 | 1 | m_fLocked | Unused
2 | 1 | m_Hidden | Unused
3 | 1 | m_f123Prefix | Unused

fTextAttr
The fTextAttr flags are packed into this parameter in the following way:
Bit
Size
Name
Contents
0 | 3 | m_nAlignment | Horizontal alignment
3 | 1 | m_fWordWrap | True if “Wrap Text” is on
4 | 3 | m_nVertAlign | Vertical alignment
7 | 1 | m_fJustLast | Unused
8 | 1 | m_fTop | Unused
9 | 1 | m_fLeft | Unused
10 | 1 | m_fBot | Unused
11 | 1 | m_fRight | Unused
12 | 4 | Reserved | Reserved


Microsoft Pocket Excel Formulas

Formulas in Pocket Excel are a perfect subset of the formulas in Desktop Excel 95 files. Refer to the “Microsoft Excel Formulas” section in Chapter 3 of the Excel 95 Developer’s Kit for detailed information on Excel formulas. The following is a list of parse things that are supported by Pocket Excel:

ptgAdd | ptgLT | ptgArea
ptgSub | ptgLE | ptgAreaV
ptgMul | ptgEQ | ptgAreaN
ptgDiv | ptgGE | ptgNameX
ptgPower | ptgGT | ptgNameXV
ptgConcat | ptgNE | ptgName
ptgInt | ptgUminus | ptgNameV
ptgNum | ptgPercent | ptgNameA
ptgStr | ptgUplus | ptgRef3d
ptgErr | ptgParen | ptgRef3dV
ptgBool | ptgMissArg | ptgRefErr3d
ptgRefErr | ptgFunc | ptgArea3d
ptgRefErrV | ptgFuncV | ptgArea3dV
ptgRef | ptgFuncVar | ptgAreaErr3d
ptgRefV | ptgFuncVarV | ptgAttr (only bitFAttrIf,
ptgRefN | ptgAreaErr | bitFAttrGoto,
ptgRefNV | ptgAreaErrV | bitFAttrSum and bitFAttrChoose)


Pocket Excel 2.0 Formulas

Pocket Excel 2.0 supports one parsething that is not supported in Pocket Excel 1.0 : ptgUPlus. Also, the ptgStr parsething is in Excel 97 format, which is as follows:

Parameter Type
Name
Description
BYTE | cch | String length in characters
BYTE | flags | Always 1 in Pocket Excel 2.0-generated parsethings
WCHAR | awch[cch] | String contents


Microsoft Pocket Word 2.0 File Format Specification

Microsoft® Pocket Word 2.0 is the word processor component of Microsoft® Pocket Office 2.0 for the Handheld PC. The Microsoft Pocket Word 2.0 file format is very similar to Rich Text Format (RTF). In fact, with one small change to the Microsoft Pocket Word 2.0 file header, any RTF reader, (for example, Microsoft® Word), can read a Microsoft Pocket Word 2.0 file. This document describes the file format of a Microsoft Pocket Word 2.0 document.

While Pocket Word 2.0 files are very similar to RTF files, there are several differences:

  • A Microsoft Pocket Word 2.0 file has the header “{\pwd2” to allow readers to identify it as a Microsoft Pocket Word 2.0 file. This compares with “{\rtf1” for RTF files, and “{\pwd1” for Microsoft Pocket Word 1.0 files. By changing a Microsoft Pocket Word header to be the RTF header, the file can usually be read by any RTF reader.
  • Microsoft Pocket Word 2.0 includes password protection of files to prevent unauthorized access. While the file header remains readable, the rest of the file is encrypted as binary data. This file format specification does not include details of the Microsoft Pocket Word 2.0 encryption algorithm.
  • All picture data in the file is held as binary data and is preceded by the “\bin” RTF token. This is standard RTF; it is mentioned here because it is more common to see picture data held as ASCII text representing hexadecimal values for the data. By storing the picture data as binary data, the storage requirements are halved.
  • The following two tokens are not standard RTF, but are recognized by Microsoft Pocket Word 2.0.
    • \pwd
    • \collapsed


Recognized Tokens

The RTF tokens recognized by Microsoft Pocket Word 2.0 form a subset of the full set of RTF tokens.

The tokens recognized by Microsoft Pocket Word 2.0 fall into the following three categories:

  • Tokens that produce specified RTF behavior
  • Tokens that are treated as other recognized tokens
  • Tokens that are preserved but have little or no effect on the display

For a list of the RTF tokens supported by Pocket Word 2.0, see Fully Recognized Tokens. Refer to RTF specification documentation for information on their usage.


Fully Recognized Tokens

These tokens are fully recognized by Microsoft Pocket Word 2.0 and produce the expected effect on the document for that RTF.

Example

Center Justify \qc

All paragraphs with this property are displayed centered justified.

Pocket Word 2.0 supports tokens for:

Document Version
Character Formatting Properties
Paragraph Formatting Properties
Color Table
Font Table
Style Sheet
Bullets and Numbering
Tabs
Objects
Pictures
Special Characters
Document Properties
Text Control
Character Set/Code Page
View Settings


Document Version

Token
Description
pwd | Microsoft Pocket Word file header
rtf | RTF file header, used for opening/saving RTF files


Character Formatting Properties

Token
Description
b | Bold
cf | Foreground color
dn | Lowered
f | Font
fs | Font size
highlight | Highlighting
i | Italic
lang | Language
nosupersub | Stop superscript or subscript
plain | Plain
revised | Revised (added text)
strike | Strikethrough
sub | Subscript
super | Superscript
ul | Underline
up | Raised
v | Hidden


Paragraph Formatting Properties

The tokens described in the following table apply to paragraphs that are not contained inside tables. Most paragraph properties are not supported by Microsoft Pocket Word 2.0 inside table cells.

Token
Description
fi | Indent first
li | Line indent
pard | Paragraph default
qc | Center justify
ql | Left justify (default, so not saved with document)
qr | Right Justify
ri | Right indent
s | Style
sa | Space after
sb | Space before
sl | Line spacing
Slmult | Line spacing multiplier


Color Table

Token
Description
blue | Blue
colortbl | Color table
green | Green
red | Red


Font Table

Token
Description
deff | Default font
fbidi | Font family bidirectional
fcharset | Character set
fdecor | Family decorative
fmodern | Family modern
fname | Real font name
fnil | Family default
fonttbl | Font table
fprq | Pitch
froman | Family roman
fscript | Family script
fswiss | Family swiss
ftech | Family technical


Style Sheet

Token
Description
stylesheet Style Sheet


Bullets and Numbering

Token
Description
pn | Paragraph numbering
pndec | Decimal
pnindent | Indent
pnlcltr | Lower case letter
pnlcrm | Lower case roman numeral
pnlvlblt | Bullet
pnlvlbody | Body
pnlvlcont | Numbering level continue
pnstart | Starting number
pntext | Text
pnucltr | Upper case letter
pnucrm | Upper case roman numeral


Tabs

Token
Description
tx Tab position


Objects

Microsoft Pocket Word 2.0 does not support objects. If an object has a device independent bitmap representation contained in its result group, Microsoft Pocket Word 2.0 will extract the picture and display it. The picture will be saved with the document, but no object RTF will be saved.

Token
Description
result Object result for RTF readers that do not recognize the object


Pictures

Microsoft Pocket Word 2.0 can support pictures defined as device-independent bitmaps or device-dependant bitmaps.

Token
Description
bin | Binary data
dibitmap | Device independent bitmap
pich | Height
pichgoal | Goal height
picscalex | Scale horizontal
picscaley | Scale vertical
pict | Picture
picw | Width
picwgoal | Goal width
wbitmap | Bitmap
wbmbitspixel | Bitmap bits per pixel
wbmplanes | Bitmap planes
wbmwidthbytes | Bitmap bytes per row


Special Characters

Token
Description
line | New line
page | New page
par | New paragraph
bullet | Bullet
ldblquote | Left double quote
lquote | Left quote
rdblquote | Right double quote
rquote | Right quote
tab | Tab


Document Properties

Token
Description
deflang | Default language
deflangfe | Default language (Far East)
deftab | Default tab stop
utf | UTF8


Text Control

Token
Description
u | Unicode
uc | Unicode character byte count


Character Set/Code Page

Token
Description
ansi | ANSI character set for document (default)
ansicpg | ANSI code page
cpg | Code page


View settings

Token
Description
collapsed | Paragraph text is collapsed in Outline view
viewkind | Current view when document opened, (Normal, Outline)
viewscale | Current zoom factor when document opened


Replaced Tokens

When Microsoft Pocket Word 2.0 opens a document, it will treat some tokens as other recognized tokens. When saving the document, the original token will not be written to the file, and another token will be written in its place.

Example

Section Default \sectd is replaced with Paragraph Default \pard

Microsoft Pocket Word 2.0 does not support Sections in documents. So any Section Default tokens found when opening a document will be saved later as Paragraph Default tokens.

Tokens that are replaced include:

Tokens Replaced with Text Characters
Tokens Treated as Other Supported Tokens
Fields


Tokens Replaced with Text Characters

Token
Displayed Character
RTF written during save
ASCII value
emdash - - 0x2D
emspace | 0x20
endash - - 0x2D
enspace | 0x20
ltrmark ? \u8206\'3f Unicode
rtlmark ? \u8207\'3f Unicode
zwj ? \u8205\'3f Unicode
zwnj ? \u8204\'3f Unicode


Tokens Treated as Other Supported Tokens

Token
Description
Treated as
Effect
deleted | Deleted text (for revision tracking) | strike | Deleted text loses deleted property, and adopts strikethrough property.
revauth | Revision Author | cf | Author information is lost, and text color changes to indicate different author.
sect | End section | pard | Section information is lost, and text reverts to default paragraph properties.
sectd | Section default | pard | Section information lost, and text reverts to default paragraph properties.
trbrdrb | Table border bottom | brdrb | Table cell bottom border saved using the cell border token \clbrdrb
trbrdrl | Table border left | brdrl | Table cell left border saved using the cell border token \clbrdrl
trbrdrr | Table border right | brdrr | Table cell right border saved using the cell border token \clbrdrr
trbrdrt | Table border top | brdrt | Table cell top border saved using the cell border token \clbrdrt
ulnone | Stop Underline | ul0 | File saved with \ul0 token


Fields

In most cases when Microsoft Pocket Word 2.0 encounters the Field group, the text contained in the Field Result subgroup will be extracted and treated as regular document text. The rest of the Field-related RTF will be ignored. The only two exceptions to this Field group handling are for the SYMBOL and HYPERLINK groups.

  • The Symbol definition is read from the data following the \fldinst token, and is not read from the field result subgroup.
  • The Hyperlink text is read from the data following the \fldinst token, and is not read from the field result subgroup.

When the document is later saved, no Field-related RTF is written to the file. The following field-related RTF tokens are supported by Microsoft Pocket Word 2.0.

Token
Description
field | Field
fldinst | Field instruction
fldrslt | Field result


Preserved but Ignored Tokens

Some tokens do not produce the full RTF-specified behavior for that RTF. The tokens are preserved, however, to be written to the file when the document is saved. This allows other RTF readers to process the tokens if necessary.

Example

Paragraph Shading \shading

Paragraphs with this property will be displayed with no shading in Microsoft Pocket Word 2.0. When the document is saved, the token is saved with the appropriate paragraphs.

Tokens that do not produce the full RTF-specified behavior include:

Character Formatting Properties
Paragraph Formatting Properties
Paragraph Borders
Paragraph Shading
Special Characters
Table Definitions
Information Group
Document Formatting Properties
Tabs
Pictures
Text Control


Character Formatting Properties

Token
Description
animtext | Animated text
caps | All capitals
disabled | Disabled
embo | Embossed
expndtw | Spacing
impr | Engraved
kerning | Kerning
lnkd | Linked
outl | Outline
protect | Protected
scaps | Small capitals
shad | Shadow
uld | Underline dotted
uldash | Underline dash
uldashd | Underline dot dash
uldashdd | Underline dot dot dash
uldb | Underline double
ulhair | Underline hairline
ulth | Underline thick
ulw | Underline word
ulwave | Underline wave


Paragraph Formatting Properties

Token
Description
hyphpar | Hyphenated paragraph
intbl | In table
keep | Keep lines together
keepn | Keep with next
ltrpar | Left to right paragraph
noline | Supress line number
nowidctlpar | No widow control
pagebb | Page break before
qj | Align jusitfied
rtlpar | Right to left paragraph
sbys | Side by side


Paragraph Borders

The following border properties are preserved for paragraphs that to not lie inside tables. Inside tables, all cell border types are treated as solid borders.

Token
Description
box | Top, left, bottom, right borders
brdrb | Bottom
brdrbar | Outside
brdrbtw | Between
brdrcf | Color
brdrdash | Dash
brdrdashsm | Dash small
brdrdb | Double
brdrdot | Dot
brdrhair | Hairline
brdrl | Left border
brdrr | Right norder
brdrs | Single
brdrsh | Shadow
brdrt | Top border
brdrth | Thick
brdrtriple | Triple
brdrw | Width
brsp | Space


Paragraph Shading

The following shading properties are preserved for paragraphs that do not lie inside tables. Shading inside tables is not preserved.

Token
Description
bgbdiag | Background backward diagonal
bgcross | Background cross
bgdcross | Background diagonal cross
bgdkbdiag | Background dark backward diagonal
bgdkcross | Background dark cross
bgdkdcross | Background dark diagonal cross
bgdkfdiag | Background dark forward diagonal
bgdkhoriz | Background dark horizontal
bgdkvert | Background dark vertical
bgfdiag | Background forward diagonal
bghoriz | Background horizonal
bgvert | Background vertical
cbpat | Color background pattern
cfpat | Color forground pattern
shading | Shading


Special Characters

Token
Description
cell | End of table cell, (displayed as tab character in document)
row | End of table row, (displayed as new line in document)


Table Definitions

Token
Description
cellx | Cell width
clbrdrb | Cell border bottom
clbrdrl | Cell border left
clbrdrr | Cell border right
clbrdrt | Cell border top
trgaph | Cell half gap
trleft | Row left indent
trowd | Row default
trqc | Row center justified
trqr | Row right justified


Information Group

The following token is only written to the file if either the \fchars or \lchars tokens are being written.

Token
Description
info Document area


Document Formatting Properties

Token
Description
fchars | List of following kinsoku characters
lchars | List of leading kinsoku characters


Tabs

Token
Description
tb | Tab bar
tldot | Leader dots
tlhyph | Leader hyphen
tlul | Leader underline
tqc | Center tab
tqdec | Decimal tab
tqr | Right tab


Pictures

Token
Description
piccropb | Crop bottom
piccropl | Crop left
piccropr | Crop right
piccropt | Crop top


Text Control

Token
Description
ltrch | Left to right characters
ltrdoc | Left to right document
rtfch | Right to left characters
rtldoc | Right to left document


(Untitled)

Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

Reason | Remedy
Destination topic not in the selected active subset. | Set active subset to an appropriate subset or to (Entire Collection).
Link is out-of-date. | Use the index or search function instead.
Link was authored incorrectly. | Use the index or search function instead.
Problems with the MSDN installation. | Uninstall the MSDN Library and then rerun Setup.

See MSDN Library Help for more information on subsets, search, the index, and installation.